summaryrefslogtreecommitdiffstats
path: root/docs/guides/onap-developer/how-to-use-docs
diff options
context:
space:
mode:
authorEric Debeau <eric.debeau@orange.com>2019-04-10 13:48:42 +0000
committerEric Debeau <eric.debeau@orange.com>2019-04-10 18:29:08 +0000
commitd6541d87f97175993b76efb0289981b3a12b0590 (patch)
tree942bfa0802eebe5d3a137f934cd0d394e6e96b59 /docs/guides/onap-developer/how-to-use-docs
parentb370f01dd1046563b7773f47d977373a12d7d721 (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')
-rw-r--r--docs/guides/onap-developer/how-to-use-docs/api-swagger-guide.rst72
-rw-r--r--docs/guides/onap-developer/how-to-use-docs/index.rst1
-rw-r--r--docs/guides/onap-developer/how-to-use-docs/myAPI1.json37
-rw-r--r--docs/guides/onap-developer/how-to-use-docs/myAPI2.json37
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"
+ }
+ }
+ }
+ }
+ }
+}