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 '>'.
61 For each API, the ``swaggerv2doc`` directive must be used as follows:
64 Note the āvā in swaggerv2doc!
65 If your JSON file has multiple endpoints, this directive does not preserve the order.
68 swaggerv2doc directive may generate errors when Swagger file contains specific
69 information. In such case, do not use this direcive.
75 .. swaggerv2doc:: myAPI1.json
79 .. swaggerv2doc:: myAPI2.json
81 It will produce the following output:
85 .. swaggerv2doc:: myAPI1.json
89 .. swaggerv2doc:: myAPI2.json