API Documentation

Swagger

The API should be described using OpenAPI specifications and available as a JSON file

A Swagger editor is available here http://editor.swagger.io/ to generate such JSON files.

As a result, you should get one JSON file per API. For example the project my has 2 API: myAPI1 and myAPI2.

• myAPI1.json

• myAPI2.json

Global API Table

It is recommended to list the following API available with an access to the Swagger JSON files to help the developers/users to play with JSON.

We propose the following table:

API name	Swagger JSON
myAPI1	link
myAPI12	link

Note

During documentation merge/publish at RTD, any file referenced in an RST file with ‘:download:’ and relative path to a contributing project repository is copied, uniquely named, and published with the generated HTML pages.

The code is available here:

.. csv-table::
   :header: "API name", "Swagger JSON"
   :widths: 10,5

   "myAPI1", ":download:`link <myAPI1.json>`"
   "myAPI2", ":download:`link <myAPI2.json>`"

Note

The syntax of <myAPI1.json> is to be taken literally. Keep ‘<’ and ‘>’.

API Swagger

For each API, the swaggerv2doc directive must be used as follows:

Note

Note the “v” in swaggerv2doc! If your JSON file has multiple endpoints, this directive does not preserve the order.

Note

swaggerv2doc directive may generate errors when Swagger file contains specific information. In such case, do not use this directive.

myAPI1
......
.. swaggerv2doc:: myAPI1.json

myAPI2
......
.. swaggerv2doc:: myAPI2.json

It will produce the following output:

myAPI1

GET /healthCheck

Displays healhcheck for my favorite component

• Description: Displays healthcheck for my favorite component

Responses

200 - Service OK

503 - Service Unavailable

myAPI2

GET /status

Displays status for my favorite component

• Description: Displays status for my favorite component

Responses

200 - Service OK

503 - Service Unavailable