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.
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|
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>`"
The syntax of <myAPI1.json> is to be taken literally. Keep ‘<’ and ‘>’.
For each API, the
swaggerv2doc directive must be used as follows:
Note the “v” in swaggerv2doc! If your JSON file has multiple endpoints, this directive does not preserve the order.
swaggerv2doc directive may generate errors when Swagger file contains specific information. In such case, do not use this direcive.
myAPI1 ...... .. swaggerv2doc:: myAPI1.json myAPI2 ...... .. swaggerv2doc:: myAPI2.json
It will produce the following output:
Displays healhcheck for my favorite component
- Description: Displays healthcheck for my favorite component
200 - Service OK
503 - Service Unavailable