From d6541d87f97175993b76efb0289981b3a12b0590 Mon Sep 17 00:00:00 2001 From: Eric Debeau Date: Wed, 10 Apr 2019 13:48:42 +0000 Subject: 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 --- .../how-to-use-docs/api-swagger-guide.rst | 72 ++++++++++++++++++++++ .../onap-developer/how-to-use-docs/index.rst | 1 + .../onap-developer/how-to-use-docs/myAPI1.json | 37 +++++++++++ .../onap-developer/how-to-use-docs/myAPI2.json | 37 +++++++++++ 4 files changed, 147 insertions(+) create mode 100644 docs/guides/onap-developer/how-to-use-docs/api-swagger-guide.rst create mode 100644 docs/guides/onap-developer/how-to-use-docs/myAPI1.json create mode 100644 docs/guides/onap-developer/how-to-use-docs/myAPI2.json (limited to 'docs/guides') 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 `_ + +A Swagger editor is available here ``_ 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 `" + "myAPI12", ":download:`link `" + + +The code is available here: + +.. code:: rst + + ..csv-table:: + :header: "API name", "Swagger JSON" + :widths: 10,5 + + "myAPI1", ":download:`link `" + "myAPI2", ":download:`link `" + +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" + } + } + } + } + } +} -- cgit 1.2.3-korg