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
  59 API Swagger
  60 -----------
  61 For each API, the ``swaggerv2doc`` directive must be used as follows:
  62
  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
  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