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:
  20
  21 - myAPI1.json
  22 - myAPI2.json
  23
  24 Global API table
  25 ----------------
  26 It is recommended to list the following API available with an access to the
  27 Swagger JSON files to help the developers/users to play with JSON.
  28
  29 We propose the following table:
  30
  31 .. csv-table::
  32    :header: "API name", "Swagger JSON"
  33    :widths: 10,5
  34
  35    "myAPI1", ":download:`link <myAPI1.json>`"
  36    "myAPI12", ":download:`link <myAPI2.json>`"
  37
  38
  39 The code is available here:
  40
  41 .. code:: rst
  42
  43    ..csv-table::
  44      :header: "API name", "Swagger JSON"
  45      :widths: 10,5
  46
  47      "myAPI1", ":download:`link <myAPI1.json>`"
  48      "myAPI2", ":download:`link <myAPI2.json>`"
  49
  50 API Swagger
  51 -----------
  52 For each API, the ``swaggerv2doc`` directive must be used as follows:
  53
  54 .. code:: rst
  55
  56    myAPI1
  57    ......
  58    .. swaggerv2doc:: myAPI1.json
  59
  60    myAPI2
  61    ......
  62    .. swaggerv2doc:: myAPI2.json
  63
  64 It will produce the following output:
  65
  66 myAPI1
  67 ......
  68 .. swaggerv2doc:: myAPI1.json
  69
  70 myAPI2
  71 ......
  72 .. swaggerv2doc:: myAPI2.json