1 .. This work is licensed under a Creative Commons Attribution 4.0
2 .. International License. http://creativecommons.org/licenses/by/4.0
3 .. Copyright 2019 Orange. All rights reserved.
13 The API should be described using OpenAPI specifications and available as a
14 `JSON file <https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md>`_
16 A Swagger editor is available here `<http://editor.swagger.io/>`_ to generate
19 As a result, you should get one JSON file per API. For example the project
20 **my** has 2 API: **myAPI1** and **myAPI2**.
27 It is recommended to list the following API available with an access to the
28 Swagger JSON files to help the developers/users to play with JSON.
30 We propose the following table:
33 :header: "API name", "Swagger JSON"
36 "myAPI1", ":download:`link <myAPI1.json>`"
37 "myAPI12", ":download:`link <myAPI2.json>`"
40 During documentation merge/publish at RTD, any file referenced in an RST file with
41 ':download:' and relative path to a contributing project repository is copied, uniquely
42 named, and published with the generated HTML pages.
44 The code is available here:
49 :header: "API name", "Swagger JSON"
52 "myAPI1", ":download:`link <myAPI1.json>`"
53 "myAPI2", ":download:`link <myAPI2.json>`"
56 The syntax of <myAPI1.json> is to be taken literally. Keep '<' and '>'.
59 Note the āvā in swaggerv2doc!
60 If your JSON file has multiple endpoints, this directive does not preserve the order.
64 For each API, the ``swaggerv2doc`` directive must be used as follows:
70 .. swaggerv2doc:: myAPI1.json
74 .. swaggerv2doc:: myAPI2.json
76 It will produce the following output:
80 .. swaggerv2doc:: myAPI1.json
84 .. swaggerv2doc:: myAPI2.json