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 <mwatkins@linuxfoundation.org>

diff --git a/docs/apis/genericresource.rst b/docs/apis/genericresource.rst
index c196838..5bead5e 100644 (file)
--- 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 <https://gerrit.onap.org/r/gitweb?p=sdnc/northbound.git;a=tree>`_.
+
+.. openapi:: ../specs/generic-resource-api.json
+   :group:
\ No newline at end of file

diff --git a/docs/conf.py b/docs/conf.py
index 3d005ec..754d827 100644 (file)
--- 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 097282b..a8683b4 100644 (file)
--- 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 (file)
index 0000000..85fa7b3
--- /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 (executable)
index 0000000..c75486f
--- /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 5200df4..673011c 100644 (file)
--- 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