Uploaded image for project: 'Active and Available Inventory'
  1. Active and Available Inventory
  2. AAI-494

Improve API Swagger Documentation

    XMLWordPrintable

    Details

    • Type: Story
    • Status: Closed
    • Priority: Medium
    • Resolution: Done
    • Affects Version/s: None
    • Fix Version/s: Beijing Release
    • Labels:
      None

      Description

      This epic is for investigating swagger documentation tools and how they can be used to make the API documentation easier for clients to reference. Right now we have the API spec document and the swagger document.

      The file is https://gerrit.onap.org/r/gitweb?p=aai/aai-common.git;a=blob;f=aai-schema/src/main/resources/aai_swagger_yaml/aai_swagger_v11.yaml;h=4447f7f3e52e38a57e06a00bf9b2a32eef64d13a;hb=8dcb9900cae95a17ca6d029a665d512b3e7b11a2

      I tried this tool:

      https://github.com/Arello-Mobile/swagger2rst

      But it fails. My belief is that our yaml file is not formatted correctly.

      Here's what is produced in HTML that we're currently providing:

      http://onap.readthedocs.io/en/latest/submodules/aai/aai-common.git/docs/platform/offeredapis.html

      We need something similar in RST format for readthedocs.

        Attachments

        1. aai_swagger_v11.html
          2.84 MB
        2. rst_fix.sh
          0.1 kB
        3. rst2html_errors.txt
          104 kB

          Issue Links

          There are no Sub-Tasks for this issue.
          No reviews matched the request. Check your Options in the drop-down menu of this sections header.

            Activity

              People

              Assignee:
              re6517 Richard Epp
              Reporter:
              jimmydot James Forsyth
              Votes:
              0 Vote for this issue
              Watchers:
              3 Start watching this issue

                Dates

                Created:
                Updated:
                Resolved: