API Documentation

Note

API Documentation Update

The API documentation has been migrated from Swagger 2.0 to OpenAPI 3.x specification.

What changed:

  • The sphinxcontrib-swaggerdoc extension has been replaced with sphinxcontrib-openapi

  • All .. swaggerv2doc:: directives have been updated to .. openapi::

  • OpenAPI 3.x provides better support for modern API features and is actively maintained

For readers: The API documentation content and functionality remain the same. OpenAPI is the successor to Swagger and offers the same capabilities with improved specification support.

For contributors: When adding new API documentation, use the .. openapi:: directive instead of the deprecated .. swaggerv2doc:: directive.

See also

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 Documentation Rendering

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

Note

The openapi directive replaces the deprecated swaggerv2doc directive. If your JSON file has multiple endpoints, this directive does not preserve the order.

Note

The openapi directive may generate errors when the specification file contains unsupported or malformed content. In such cases, do not use this directive.

myAPI1
......
.. openapi:: myAPI1.json

myAPI2
......
.. openapi:: myAPI2.json

It will produce the following output:

myAPI1

GET /healthCheck

Displays healhcheck for my favorite component

Displays healthcheck for my favorite component

Status Codes:

myAPI2

GET /status

Displays status for my favorite component

Displays status for my favorite component

Status Codes: