| Eric Debeau | d6541d8 | 2019-04-10 13:48:42 +0000 | [diff] [blame] | 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. |
| 4 | |
| 5 | .. _api-swagger-guide: |
| 6 | |
| 7 | API documentation |
| 8 | ================= |
| 9 | |
| 10 | Swagger |
| 11 | ------- |
| 12 | |
| 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>`_ |
| 15 | |
| 16 | A Swagger editor is available here `<http://editor.swagger.io/>`_ to generate |
| 17 | such JSON files. |
| 18 | |
| Eric Debeau | 3050a39 | 2019-04-17 14:55:18 +0000 | [diff] [blame] | 19 | As a result, you should get one JSON file per API. For example the project |
| 20 | **my** has 2 API: **myAPI1** and **myAPI2**. |
| Eric Debeau | d6541d8 | 2019-04-10 13:48:42 +0000 | [diff] [blame] | 21 | |
| 22 | - myAPI1.json |
| 23 | - myAPI2.json |
| 24 | |
| 25 | Global API table |
| 26 | ---------------- |
| 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. |
| 29 | |
| 30 | We propose the following table: |
| 31 | |
| 32 | .. csv-table:: |
| 33 | :header: "API name", "Swagger JSON" |
| 34 | :widths: 10,5 |
| 35 | |
| 36 | "myAPI1", ":download:`link <myAPI1.json>`" |
| 37 | "myAPI12", ":download:`link <myAPI2.json>`" |
| 38 | |
| Eric Debeau | 3050a39 | 2019-04-17 14:55:18 +0000 | [diff] [blame] | 39 | .. note:: |
| 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. |
| Eric Debeau | d6541d8 | 2019-04-10 13:48:42 +0000 | [diff] [blame] | 43 | |
| 44 | The code is available here: |
| 45 | |
| 46 | .. code:: rst |
| 47 | |
| Eric Debeau | 3050a39 | 2019-04-17 14:55:18 +0000 | [diff] [blame] | 48 | .. csv-table:: |
| 49 | :header: "API name", "Swagger JSON" |
| 50 | :widths: 10,5 |
| Eric Debeau | d6541d8 | 2019-04-10 13:48:42 +0000 | [diff] [blame] | 51 | |
| Eric Debeau | 3050a39 | 2019-04-17 14:55:18 +0000 | [diff] [blame] | 52 | "myAPI1", ":download:`link <myAPI1.json>`" |
| 53 | "myAPI2", ":download:`link <myAPI2.json>`" |
| 54 | |
| 55 | .. note:: |
| 56 | The syntax of <myAPI1.json> is to be taken literally. Keep '<' and '>'. |
| 57 | |
| Eric Debeau | d6541d8 | 2019-04-10 13:48:42 +0000 | [diff] [blame] | 58 | |
| 59 | API Swagger |
| 60 | ----------- |
| 61 | For each API, the ``swaggerv2doc`` directive must be used as follows: |
| 62 | |
| Eric Debeau | 9fcfeec | 2019-05-13 13:09:08 +0000 | [diff] [blame] | 63 | .. note:: |
| 64 | Note the “v” in swaggerv2doc! |
| 65 | If your JSON file has multiple endpoints, this directive does not preserve the order. |
| 66 | |
| 67 | .. note:: |
| 68 | swaggerv2doc directive may generate errors when Swagger file contains specific |
| 69 | information. In such case, do not use this direcive. |
| 70 | |
| Eric Debeau | d6541d8 | 2019-04-10 13:48:42 +0000 | [diff] [blame] | 71 | .. code:: rst |
| 72 | |
| 73 | myAPI1 |
| 74 | ...... |
| 75 | .. swaggerv2doc:: myAPI1.json |
| 76 | |
| 77 | myAPI2 |
| 78 | ...... |
| 79 | .. swaggerv2doc:: myAPI2.json |
| 80 | |
| 81 | It will produce the following output: |
| 82 | |
| 83 | myAPI1 |
| 84 | ...... |
| 85 | .. swaggerv2doc:: myAPI1.json |
| 86 | |
| 87 | myAPI2 |
| 88 | ...... |
| 89 | .. swaggerv2doc:: myAPI2.json |