From: halil.cakal Date: Tue, 2 Aug 2022 12:52:59 +0000 (+0100) Subject: Replace openapi docs gen lib with redoc X-Git-Tag: 2.4.0~6 X-Git-Url: https://gerrit.o-ran-sc.org/r/gitweb?p=sim%2Fa1-interface.git;a=commitdiff_plain;h=6e325de83c8469a93500a8c0b8f4458158ed6905 Replace openapi docs gen lib with redoc Issue-ID: NONRTRIC-771 Change-Id: Ibfeb6a3a1ca7e6e50f111e871c00c9ad3958378b Signed-off-by: halil.cakal --- 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 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 --- 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