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 |
|
myAPI12 |
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