docs/guides/onap-developer/how-to-use-docs/api-swagger-guide.rst

   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
  19 As a result, you should get one JSON file per API. For example the project
  20 **my** has 2 API: **myAPI1** and **myAPI2**.
  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
  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.
  43
  44 The code is available here:
  45
  46 .. code:: rst
  47
  48    .. csv-table::
  49       :header: "API name", "Swagger JSON"
  50       :widths: 10,5
  51
  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
  58 .. note::
  59    Note the “v” in  swaggerv2doc!
  60    If your JSON file has multiple endpoints, this directive does not preserve the order.
  61
  62 API Swagger
  63 -----------
  64 For each API, the ``swaggerv2doc`` directive must be used as follows:
  65
  66 .. code:: rst
  67
  68    myAPI1
  69    ......
  70    .. swaggerv2doc:: myAPI1.json
  71
  72    myAPI2
  73    ......
  74    .. swaggerv2doc:: myAPI2.json
  75
  76 It will produce the following output:
  77
  78 myAPI1
  79 ......
  80 .. swaggerv2doc:: myAPI1.json
  81
  82 myAPI2
  83 ......
  84 .. swaggerv2doc:: myAPI2.json