diff options
author | 2019-04-10 13:48:42 +0000 | |
---|---|---|
committer | 2019-04-10 18:29:08 +0000 | |
commit | d6541d87f97175993b76efb0289981b3a12b0590 (patch) | |
tree | 942bfa0802eebe5d3a137f934cd0d394e6e96b59 /docs/guides/onap-developer/how-to-use-docs | |
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')
4 files changed, 147 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 diff --git a/docs/guides/onap-developer/how-to-use-docs/index.rst b/docs/guides/onap-developer/how-to-use-docs/index.rst index a2cdd6e6b..90c657501 100644 --- a/docs/guides/onap-developer/how-to-use-docs/index.rst +++ b/docs/guides/onap-developer/how-to-use-docs/index.rst @@ -10,6 +10,7 @@ Creating Documentation documentation-guide style-guide include-documentation + api-swagger-guide converting-formats addendum diff --git a/docs/guides/onap-developer/how-to-use-docs/myAPI1.json b/docs/guides/onap-developer/how-to-use-docs/myAPI1.json new file mode 100644 index 000000000..b611ad81c --- /dev/null +++ b/docs/guides/onap-developer/how-to-use-docs/myAPI1.json @@ -0,0 +1,37 @@ +{ + "swagger" : "2.0", + "info" : { + "description" : "my API 1", + "version" : "1.0.0", + "title" : "API example", + "contact" : { + "email" : "onap@orange.com" + }, + "license" : { + "name" : "Apache 2.0", + "url" : "http://www.apache.org/licenses/LICENSE-2.0.html" + } + }, + "host" : "serverRoot", + "basePath" : "/healthCheck", + "schemes" : [ "https" ], + "produces": [ + "application/json;charset=utf-8" + ], + "paths" : { + "/healthCheck" : { + "get" : { + "summary" : "Displays healhcheck for my favorite component", + "description" : "Displays healthcheck for my favorite component", + "responses": { + "200": { + "description": "Service OK" + }, + "503" : { + "description" : "Service Unavailable" + } + } + } + } + } +} diff --git a/docs/guides/onap-developer/how-to-use-docs/myAPI2.json b/docs/guides/onap-developer/how-to-use-docs/myAPI2.json new file mode 100644 index 000000000..473d351b2 --- /dev/null +++ b/docs/guides/onap-developer/how-to-use-docs/myAPI2.json @@ -0,0 +1,37 @@ +{ + "swagger" : "2.0", + "info" : { + "description" : "my API 2", + "version" : "1.0.0", + "title" : "API example", + "contact" : { + "email" : "onap@orange.com" + }, + "license" : { + "name" : "Apache 2.0", + "url" : "http://www.apache.org/licenses/LICENSE-2.0.html" + } + }, + "host" : "serverRoot", + "basePath" : "/status", + "schemes" : [ "https" ], + "produces": [ + "application/json;charset=utf-8" + ], + "paths" : { + "/status" : { + "get" : { + "summary" : "Displays status for my favorite component", + "description" : "Displays status for my favorite component", + "responses": { + "200": { + "description": "Service OK" + }, + "503" : { + "description" : "Service Unavailable" + } + } + } + } + } +} |