diff options
author | Eric Debeau <eric.debeau@orange.com> | 2019-04-10 13:48:42 +0000 |
---|---|---|
committer | Eric Debeau <eric.debeau@orange.com> | 2019-04-10 18:29:08 +0000 |
commit | d6541d87f97175993b76efb0289981b3a12b0590 (patch) | |
tree | 942bfa0802eebe5d3a137f934cd0d394e6e96b59 /docs/guides/onap-developer/how-to-use-docs/api-swagger-guide.rst | |
parent | b370f01dd1046563b7773f47d977373a12d7d721 (diff) |
API documentation guide
Guide how to use Swagger and swaggerv2dcc directive
Add 2 JSON Swagger files
Add code block
Change-Id: If3af3f20509db2cc47bdb2cf3db9b44d8a1bcdc7
Issue-ID: DOC-426
Signed-off-by: Eric Debeau <eric.debeau@orange.com>
Diffstat (limited to 'docs/guides/onap-developer/how-to-use-docs/api-swagger-guide.rst')
-rw-r--r-- | docs/guides/onap-developer/how-to-use-docs/api-swagger-guide.rst | 72 |
1 files changed, 72 insertions, 0 deletions
diff --git a/docs/guides/onap-developer/how-to-use-docs/api-swagger-guide.rst b/docs/guides/onap-developer/how-to-use-docs/api-swagger-guide.rst new file mode 100644 index 000000000..d5e2099a5 --- /dev/null +++ b/docs/guides/onap-developer/how-to-use-docs/api-swagger-guide.rst @@ -0,0 +1,72 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 +.. International License. http://creativecommons.org/licenses/by/4.0 +.. Copyright 2019 Orange. All rights reserved. + +.. _api-swagger-guide: + +API documentation +================= + +Swagger +------- + +The API should be described using OpenAPI specifications and available as a +`JSON file <https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md>`_ + +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: + +- 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: + +.. csv-table:: + :header: "API name", "Swagger JSON" + :widths: 10,5 + + "myAPI1", ":download:`link <myAPI1.json>`" + "myAPI12", ":download:`link <myAPI2.json>`" + + +The code is available here: + +.. code:: rst + + ..csv-table:: + :header: "API name", "Swagger JSON" + :widths: 10,5 + + "myAPI1", ":download:`link <myAPI1.json>`" + "myAPI2", ":download:`link <myAPI2.json>`" + +API Swagger +----------- +For each API, the ``swaggerv2doc`` directive must be used as follows: + +.. code:: rst + + myAPI1 + ...... + .. swaggerv2doc:: myAPI1.json + + myAPI2 + ...... + .. swaggerv2doc:: myAPI2.json + +It will produce the following output: + +myAPI1 +...... +.. swaggerv2doc:: myAPI1.json + +myAPI2 +...... +.. swaggerv2doc:: myAPI2.json |