diff options
| author |   Eric Debeau <eric.debeau@orange.com> | 2019-04-17 14:55:18 +0000 |
|---|---|---|
| committer | Eric Debeau <eric.debeau@orange.com> | 2019-04-18 08:56:03 +0000 |
| commit | 3050a39344f7beacf917cffc53dc79a75b9c8e50 (patch) | |
| tree | b332a2938e9ba3ff60800c08113775c07dfd431e | |
| parent | ce27bc91e795506c2d2a69dc0365a0597c0aec68 (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>
| -rw-r--r-- | docs/guides/onap-developer/how-to-use-docs/api-swagger-guide.rst | 24 |
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 ----------- |