From 43ae207068598e1c3d05475c492f0a3539f24880 Mon Sep 17 00:00:00 2001 From: Matthew Watkins Date: Tue, 27 Jan 2026 15:27:35 +0000 Subject: [PATCH] Chore: Add sphinxcontrib-openapi for API documentation Replace the swaggerv2doc directive usage in genericresource.rst with the actively maintained sphinxcontrib-openapi extension. Changes: - Add sphinxcontrib-openapi==0.7.0 to requirements and conf.py (pinned to avoid sphinx-mdinclude/docutils incompatibility) - Add POSIX-compatible download script to fetch OpenAPI specs during build - Update genericresource.rst to use openapi directive - Remove unnecessary OpenStack yoga constraints from docs tox.ini - Retain sphinxcontrib-swaggerdoc module (removal in separate change) Issue-ID: CIMAN-33 Change-Id: Ic4b1a5ae8740bce998cf179262e3c9beb8716e47 Signed-off-by: Matthew Watkins --- docs/apis/genericresource.rst | 21 ++++++++++++++++++++- docs/conf.py | 5 +++-- docs/requirements-docs.txt | 4 +++- docs/specs/.gitignore | 3 +++ docs/specs/download-specs.sh | 40 ++++++++++++++++++++++++++++++++++++++++ docs/tox.ini | 5 ++--- 6 files changed, 71 insertions(+), 7 deletions(-) create mode 100644 docs/specs/.gitignore create mode 100755 docs/specs/download-specs.sh diff --git a/docs/apis/genericresource.rst b/docs/apis/genericresource.rst index c1968389..5bead5e3 100644 --- a/docs/apis/genericresource.rst +++ b/docs/apis/genericresource.rst @@ -1,4 +1,23 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. + +.. _generic-resource-api: + +==================== GENERIC-RESOURCE-API ==================== -.. swaggerv2doc:: https://gerrit.onap.org/r/gitweb?p=sdnc/northbound.git;a=blob_plain;f=generic-resource-api/model/swagger/src/main/json/generic-resource.json;h=1b7454b5dddb37e4c8540f3f8f241747500a36c1;hb=refs/heads/guilin +Overview +-------- + +The Generic Resource API provides a model-driven approach for managing and configuring +network services in ONAP. It enables the Software Defined Network Controller (SDNC) +to handle generic resource operations for service provisioning and lifecycle management. + +API Specification +----------------- + +The following API documentation is generated from the OpenAPI/Swagger specification +maintained in the `sdnc/northbound repository `_. + +.. openapi:: ../specs/generic-resource-api.json + :group: \ No newline at end of file diff --git a/docs/conf.py b/docs/conf.py index 3d005ec3..754d8273 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -21,8 +21,9 @@ extensions = [ 'sphinx.ext.graphviz', 'sphinxcontrib.blockdiag', 'sphinxcontrib.seqdiag', - 'sphinxcontrib.swaggerdoc', - 'sphinxcontrib.plantuml' + 'sphinxcontrib.swaggerdoc', # TODO: Remove in separate change (unmaintained) + 'sphinxcontrib.plantuml', + 'sphinxcontrib.openapi' ] # diff --git a/docs/requirements-docs.txt b/docs/requirements-docs.txt index 097282b9..a8683b41 100644 --- a/docs/requirements-docs.txt +++ b/docs/requirements-docs.txt @@ -1,8 +1,10 @@ sphinx>=4.2.0 # BSD sphinx-rtd-theme>=1.0.0 # MIT +Pillow<10 # Diagram extensions (not compatible with Pillow>=10) sphinxcontrib-blockdiag # BSD sphinxcontrib-seqdiag # BSD -sphinxcontrib-swaggerdoc +sphinxcontrib-openapi==0.7.0 # BSD - pinned to avoid sphinx-mdinclude/docutils incompatibility +sphinxcontrib-swaggerdoc # TODO: Remove in separate change (unmaintained) sphinxcontrib-spelling sphinxcontrib-plantuml six diff --git a/docs/specs/.gitignore b/docs/specs/.gitignore new file mode 100644 index 00000000..85fa7b3b --- /dev/null +++ b/docs/specs/.gitignore @@ -0,0 +1,3 @@ +# Downloaded OpenAPI/Swagger specification files +# These are fetched during the documentation build process +*.json \ No newline at end of file diff --git a/docs/specs/download-specs.sh b/docs/specs/download-specs.sh new file mode 100755 index 00000000..c75486fb --- /dev/null +++ b/docs/specs/download-specs.sh @@ -0,0 +1,40 @@ +#!/bin/sh +# SPDX-License-Identifier: Apache-2.0 +# Copyright 2024 ONAP Contributors +# +# Script to download OpenAPI/Swagger specifications from remote repositories +# for use with sphinxcontrib-openapi documentation generation. + +set -e + +# Get the directory where this script is located (POSIX-compatible) +SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)" + +# Generic Resource API spec from sdnc/northbound repository +# Using master branch for latest version +GENERIC_RESOURCE_API_URL="https://gerrit.onap.org/r/gitweb?p=sdnc/northbound.git;a=blob_plain;f=generic-resource-api/model/swagger/src/main/json/generic-resource.json;hb=refs/heads/master" +GENERIC_RESOURCE_API_FILE="${SCRIPT_DIR}/generic-resource-api.json" + +echo "Downloading OpenAPI specifications..." + +# Download Generic Resource API spec +echo " - Downloading Generic Resource API spec..." +if curl -sSfL -o "${GENERIC_RESOURCE_API_FILE}" "${GENERIC_RESOURCE_API_URL}"; then + echo " Successfully downloaded: ${GENERIC_RESOURCE_API_FILE}" +else + echo " WARNING: Failed to download Generic Resource API spec" + echo " Creating placeholder file..." + cat > "${GENERIC_RESOURCE_API_FILE}" << 'EOF' +{ + "swagger": "2.0", + "info": { + "title": "Generic Resource API", + "description": "API specification temporarily unavailable. Please refer to the sdnc/northbound repository for the latest specification.", + "version": "1.0.0" + }, + "paths": {} +} +EOF +fi + +echo "Done." \ No newline at end of file diff --git a/docs/tox.ini b/docs/tox.ini index 5200df4f..673011ca 100644 --- a/docs/tox.ini +++ b/docs/tox.ini @@ -7,9 +7,9 @@ skipsdist = true basepython = python3.8 deps = -r{toxinidir}/requirements-docs.txt - -chttps://releases.openstack.org/constraints/upper/yoga -chttps://git.onap.org/doc/plain/etc/upper-constraints.onap.txt commands = + sh {toxinidir}/specs/download-specs.sh sphinx-build -W -b html -n -d {envtmpdir}/doctrees ./ {toxinidir}/_build/html echo "Generated docs available in {toxinidir}/_build/html" allowlist_externals = @@ -28,8 +28,7 @@ allowlist_externals = echo basepython = python3.8 deps = -r{toxinidir}/requirements-docs.txt - -chttps://releases.openstack.org/constraints/upper/yoga - -chttps://git.onap.org/doc/plain/etc/upper-constraints.onap.txt?h=master + -chttps://git.onap.org/doc/plain/etc/upper-constraints.onap.txt commands = sphinx-build -W -q -b spelling -d {envtmpdir}/doctrees {toxinidir} {toxinidir}/_build/spellcheck -- 2.16.6