From 6e325de83c8469a93500a8c0b8f4458158ed6905 Mon Sep 17 00:00:00 2001 From: "halil.cakal" Date: Tue, 2 Aug 2022 13:52:59 +0100 Subject: [PATCH] Replace openapi docs gen lib with redoc Issue-ID: NONRTRIC-771 Change-Id: Ibfeb6a3a1ca7e6e50f111e871c00c9ad3958378b Signed-off-by: halil.cakal --- api/EXT_SRV_api.yaml | 205 ---------------------------------------------- docs/callout-server.rst | 15 +++- docs/conf.py | 20 ++++- docs/images/yaml_logo.png | Bin 0 -> 3477 bytes tox.ini | 4 +- 5 files changed, 31 insertions(+), 213 deletions(-) delete mode 100644 api/EXT_SRV_api.yaml create mode 100644 docs/images/yaml_logo.png diff --git a/api/EXT_SRV_api.yaml b/api/EXT_SRV_api.yaml deleted file mode 100644 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 --- 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 --- 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 index 0000000000000000000000000000000000000000..0492eb4bac42eda52e071cd68ac9c23cb606f72c GIT binary patch literal 3477 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 literal 0 HcmV?d00001 diff --git a/tox.ini b/tox.ini index afa3e38..e09164c 100644 --- 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 -- 2.16.6