summaryrefslogtreecommitdiffstats
path: root/docs/guides/onap-developer/how-to-use-docs
diff options
context:
space:
mode:
authorEric Debeau <eric.debeau@orange.com>2019-04-17 14:55:18 +0000
committerEric Debeau <eric.debeau@orange.com>2019-04-18 08:56:03 +0000
commit3050a39344f7beacf917cffc53dc79a75b9c8e50 (patch)
treeb332a2938e9ba3ff60800c08113775c07dfd431e /docs/guides/onap-developer/how-to-use-docs
parentce27bc91e795506c2d2a69dc0365a0597c0aec68 (diff)
Correction to documentation guide for API
Add some notes to explain JSON file location and generation Issue-ID: DOC-426 Change-Id: Ifb617308b9548f892343b72fb7d885d17973d058 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.rst24
1 files changed, 18 insertions, 6 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
index d5e2099a5..9d3a7f6fc 100644
--- 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
@@ -16,7 +16,8 @@ The API should be described using OpenAPI specifications and available as a
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:
+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
@@ -35,17 +36,28 @@ We propose the following table:
"myAPI1", ":download:`link <myAPI1.json>`"
"myAPI12", ":download:`link <myAPI2.json>`"
+.. 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:
.. code:: rst
- ..csv-table::
- :header: "API name", "Swagger JSON"
- :widths: 10,5
+ .. csv-table::
+ :header: "API name", "Swagger JSON"
+ :widths: 10,5
- "myAPI1", ":download:`link <myAPI1.json>`"
- "myAPI2", ":download:`link <myAPI2.json>`"
+ "myAPI1", ":download:`link <myAPI1.json>`"
+ "myAPI2", ":download:`link <myAPI2.json>`"
+
+.. note::
+ The syntax of <myAPI1.json> is to be taken literally. Keep '<' and '>'.
+
+.. note::
+ Note the ā€œvā€ in swaggerv2doc!
+ If your JSON file has multiple endpoints, this directive does not preserve the order.
API Swagger
-----------