Replace openapi docs gen lib with redoc

Issue-ID: NONRTRIC-771
Change-Id: Ibfeb6a3a1ca7e6e50f111e871c00c9ad3958378b
Signed-off-by: halil.cakal <halil.cakal@est.tech>

diff --git a/api/EXT_SRV_api.yaml b/api/EXT_SRV_api.yaml
deleted file mode 100644 (file)
index 043e984..0000000
--- a/api/EXT_SRV_api.yaml
+++ /dev/null
@@ -1,205 +0,0 @@
-openapi: 3.0.0
-info:
-  title: 'External Server for A1 simulator'
-  version: 0.0.1
-  description: |
-    External test server.
-    © 2022, O-RAN Alliance.
-    All rights reserved.
-externalDocs:
-  description: 'An external server building CRUD RestFUL APIs which is provisioned by A1 simulator. It will be a refrence point for the callouts'
-  url: 'https://docs.o-ran-sc.org/projects/o-ran-sc-sim-a1-interface/en/latest/external-server.html'
-servers:
-  - url: '{apiRoot}'
-    variables:
-      apiRoot:
-        default: 'http://www.example.com'
-paths:
-  '/a1policies':
-    get:
-      operationId: server.get_all_a1_policies
-      description: 'Get all a1 policies'
-      tags:
-      - All a1policies
-      responses:
-        200:
-          description: 'Array of all a1 policies'
-          content:
-            application/json:
-              schema:
-                type: array
-                items:
-                  "$ref": "#/components/schemas/A1PolicyObject"
-                minItems: 0
-        429:
-          "$ref": "#/components/responses/429-TooManyRequests"
-        503:
-          "$ref": "#/components/responses/503-ServiceUnavailable"
-  '/a1policy/{a1policyId}':
-    parameters:
-      - name: a1policyId
-        in: path
-        required: true
-        schema:
-          "$ref": "#/components/schemas/A1PolicyId"
-    get:
-      operationId: server.get_a1_policy
-      description: 'Query for an A1 policy'
-      tags:
-      - Single A1 Policy Object
-      responses:
-        200:
-          description: 'The requested A1 policy object'
-          content:
-            application/json:
-              schema:
-                "$ref": "#/components/schemas/A1PolicyObject"
-        404:
-          "$ref": "#/components/responses/404-NotFound"
-        409:
-          "$ref": "#/components/responses/409-Conflict"
-        429:
-          "$ref": "#/components/responses/429-TooManyRequests"
-        503:
-          "$ref": "#/components/responses/503-ServiceUnavailable"
-    put:
-      operationId: server.put_a1_policy
-      description: 'Create an A1 policy'
-      tags:
-      - Individual A1 policy Object
-      requestBody:
-        required: true
-        content:
-          application/json:
-            schema:
-              "$ref": "#/components/schemas/A1PolicyObject"
-      responses:
-        200:
-          description: 'The A1 policy was updated'
-          content:
-            application/json:
-              schema:
-                "$ref": "#/components/schemas/A1PolicyObject"
-        201:
-          description: 'The A1 policy was created'
-          content:
-            application/json:
-              schema:
-                "$ref": "#/components/schemas/A1PolicyObject"
-          headers:
-            Location:
-              description: 'Contains the URI of the created A1 policy'
-              required: true
-              schema:
-                type: string
-        400:
-          "$ref": "#/components/responses/400-BadRequest"
-        409:
-          "$ref": "#/components/responses/409-Conflict"
-        429:
-          "$ref": "#/components/responses/429-TooManyRequests"
-        503:
-          "$ref": "#/components/responses/503-ServiceUnavailable"
-        507:
-          "$ref": "#/components/responses/507-InsufficientStorage"
-
-    delete:
-      operationId: server.delete_a1_policy
-      description: 'Delete an A1 policy'
-      tags:
-      - Individual a1policy Object
-      responses:
-        204:
-          description: 'The A1 policy was deleted'
-        404:
-          "$ref": "#/components/responses/404-NotFound"
-        429:
-          "$ref": "#/components/responses/429-TooManyRequests"
-        503:
-          "$ref": "#/components/responses/503-ServiceUnavailable"
-
-components:
-  schemas:
-    #
-    # Representation objects
-    #
-    A1PolicyObject:
-      title: 'Title'
-      description: 'A generic A1 policy object'
-      type: object
-
-    ProblemDetails:
-      description: 'A problem detail to carry details in a HTTP response according to RFC 7807'
-      type: object
-      properties:
-        type:
-          type: string
-        title:
-          type: string
-        status:
-          type: number
-        detail:
-          type: string
-        instance:
-          type: string
-
-    #
-    # Simple data types
-    #
-    JsonSchema:
-      description: 'A JSON schema following http://json-schema.org/draft-07/schema'
-      type: object
-
-    A1PolicyId:
-      description: 'A1 policy identifier.'
-      type: string
-
-  responses:
-    400-BadRequest:
-      description: 'A1 policy not properly formulated or not related to the method'
-      content:
-        application/problem+json:
-          schema:
-            "$ref": "#/components/schemas/ProblemDetails"
-
-    404-NotFound:
-      description: 'No resource found at the URI'
-      content:
-        application/problem+json:
-          schema:
-            "$ref": "#/components/schemas/ProblemDetails"
-
-    405-MethodNotAllowed:
-      description: 'Method not allowed for the URI'
-      content:
-        application/problem+json:
-          schema:
-            "$ref": "#/components/schemas/ProblemDetails"
-
-    409-Conflict:
-      description: 'Request could not be processed in the current state of the resource'
-      content:
-        application/problem+json:
-          schema:
-            "$ref": "#/components/schemas/ProblemDetails"
-
-    429-TooManyRequests:
-      description: 'Too many requests have been sent in a given amount of time'
-      content:
-        application/problem+json:
-          schema:
-            "$ref": "#/components/schemas/ProblemDetails"
-
-    503-ServiceUnavailable:
-      description: 'The provider is currently unable to handle the request due to a temporary overload'
-      content:
-        application/problem+json:
-          schema:
-            "$ref": "#/components/schemas/ProblemDetails"
-
-    507-InsufficientStorage:
-      description: 'The method could not be performed on the resource because the provider is unable to store the representation needed to successfully complete the request'
-      content:
-        application/problem+json:
-          schema:
-            "$ref": "#/components/schemas/ProblemDetails"

diff --git a/docs/callout-server.rst b/docs/callout-server.rst
index 4a9448a..d670468 100755 (executable)
--- a/docs/callout-server.rst
+++ b/docs/callout-server.rst
@@ -8,6 +8,9 @@
 .. |nbh| unicode:: 0x2011
    :trim:
 
+.. |yaml-icon| image:: ./images/yaml_logo.png
+                  :width: 40px
+
 =====================
 Callout Server
 =====================
@@ -19,8 +22,16 @@ The O-RAN SC external server is an extension for Near-RealTime RIC simulator. It
 
 The details of API definitions are being explained below:
 
-.. Generates content from EXT_SRV_api.yaml
-.. openapi:: ../api/EXT_SRV_api.yaml
+See `Callout server API <./EXT_SRV_api.html>`_ for full details of the API.
+
+The API is also described in YAML:
+
+
+.. csv-table::
+   :header: "API name", "|yaml-icon|"
+   :widths: 10,5
+
+   "Callout Server API", ":download:`link <../near-rt-ric-simulator/test/EXT_SRV/api/EXT_SRV_api.yaml>`"
 
 
 Admin Functions

diff --git a/docs/conf.py b/docs/conf.py
index 7a27615..e4fa58d 100644 (file)
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -1,13 +1,25 @@
 from docs_conf.conf import *
 
+branch = 'latest'
+
 language = 'en'
 
 linkcheck_ignore = [
     'http://localhost.*',
     'http://127.0.0.1.*',
-    'https://gerrit.o-ran-sc.org.*'
+    'https://gerrit.o-ran-sc.org.*',
+    './EXT_SRV_api.html', #Generated file that doesn't exist at link check.
 ]
 
-extensions = [
-   'sphinxcontrib.openapi',
-]
+extensions = ['sphinxcontrib.redoc']
+
+redoc = [
+            {
+                'name': 'CALLOUT SERVER',
+                'page': 'EXT_SRV_api',
+                'spec': '../near-rt-ric-simulator/test/EXT_SRV/api/EXT_SRV_api.yaml',
+                'embed': True,
+            }
+        ]
+
+redoc_uri = 'https://cdn.jsdelivr.net/npm/redoc@next/bundles/redoc.standalone.js'

diff --git a/docs/images/yaml_logo.png b/docs/images/yaml_logo.png
new file mode 100644 (file)
index 0000000..0492eb4
Binary files /dev/null and b/docs/images/yaml_logo.png differ

diff --git a/tox.ini b/tox.ini
index afa3e38..e09164c 100644 (file)
--- a/tox.ini
+++ b/tox.ini
@@ -53,7 +53,7 @@ deps =
     sphinx
     sphinx-rtd-theme
     sphinxcontrib-httpdomain
-    sphinxcontrib-openapi==0.6.0
+    sphinxcontrib-redoc
     recommonmark
     lfdocs-conf
 commands =
@@ -66,7 +66,7 @@ basepython = python3.8
 deps = sphinx
        sphinx-rtd-theme
        sphinxcontrib-httpdomain
-       sphinxcontrib-openapi==0.6.0
+       sphinxcontrib-redoc
        recommonmark
        lfdocs-conf
 commands = sphinx-build -W -b linkcheck -d {envtmpdir}/doctrees ./docs/ {toxinidir}/docs/_build/linkcheck