Publish open api spec on AWX for community use (#16221)

* Added link and ref to openAPI spec for community

* Update docs/docsite/rst/contributor/openapi_link.rst

Co-authored-by: Don Naro <dnaro@redhat.com>

* add sphinxcontrib-redoc to requirements

* sphinxcontrib.redoc configuration

* create openapi directory and files

* update download script for both schema files

* suppress warning for redoc

* update labels

* fix extra closing parenthesis

* update schema url

* exclude doc config and download script

The Sphinx configuration (conf.py) and schema download script
(download-json.py) are not application logic and used only for building
documentation. Coverage requirements for these files are overkill.

* exclude only the sphinx config file

---------

Co-authored-by: Don Naro <dnaro@redhat.com>

docs/docsite/conf.py

@@ -1,6 +1,7 @@
 import sys
 import os
 import shlex
+import warnings
 
 from datetime import datetime
 from importlib import import_module
@@ -8,10 +9,10 @@ from importlib import import_module
 sys.path.insert(0, os.path.abspath('./rst/rest_api/_swagger'))
 
 project = u'Ansible AWX'
-copyright = u'2024, Red Hat'
+copyright = u'2026, Red Hat'
 author = u'Red Hat'
 
-pubdateshort = '2024-11-22'
+pubdateshort = '2026-01-07'
 pubdate = datetime.strptime(pubdateshort, '%Y-%m-%d').strftime('%B %d, %Y')
 
 # The name for this set of Sphinx documents.  If None, it defaults to
@@ -35,6 +36,7 @@ extensions = [
     'sphinx.ext.coverage',
     'sphinx.ext.ifconfig',
     'sphinx_ansible_theme',
+    'sphinxcontrib.redoc',
     'notfound.extension',
     'swagger',
 ]
@@ -61,6 +63,27 @@ language = 'en'
 locale_dirs = ['locale/']  # path is example but recommended.
 gettext_compact = False  # optional.
 
+redoc = [
+    {
+        'name': 'AWX OpenAPI Reference',
+        'page': 'open_api/explorer',
+        'spec': 'rst/open_api/schema.json',
+        'embed': True,
+        'opts': {
+            'suppress-warnings': True,
+            'hide-hostname': True,
+        }
+    }
+]
+
+# Suppress pkg_resources deprecation from sphinxcontrib-redoc
+warnings.filterwarnings(
+    'ignore',
+    message='pkg_resources is deprecated',
+    category=UserWarning,
+    module='sphinxcontrib.redoc',
+)
+
 rst_epilog = """
 .. |atapi| replace:: *AWX API Guide*
 .. |atrn| replace:: *AWX Release Notes*
@@ -89,3 +112,4 @@ rst_epilog = """
     pubdateshort,
     pubdate,
 )
+

docs/docsite/download-json.py

@@ -0,0 +1,19 @@
+import requests
+
+downloads = [
+    {"url": "https://awx-public-ci-files.s3.amazonaws.com/community-docs/swagger.json", "path": "./docs/docsite/rst/rest_api/_swagger/swagger.json"},
+    {"url": "https://s3.amazonaws.com/awx-public-ci-files/awx/devel/schema.json", "path": "./docs/docsite/rst/open_api/schema.json"},
+]
+
+for item in downloads:
+    url = item["url"]
+    filepath = item["path"]
+
+    response = requests.get(url)
+
+    if response.status_code == 200:
+        with open(filepath, 'wb') as file:
+            file.write(response.content)
+        print(f"JSON file downloaded to {filepath}")
+    else:
+        print(f"Request failed with status code: {response.status_code}")

docs/docsite/requirements.in

@@ -3,6 +3,8 @@
 sphinx # Tooling to build HTML from RST source.
 sphinx-ansible-theme # Ansible community theme for Sphinx doc builds.
 sphinx-notfound-page # Sphinx extension for custom 404 page.
+sphinxcontrib-redoc # Renders OpenAPI spec in human readable format.
+setuptools >= 65.0 # Provides pkg_resources module for compatibility. Needed by sphinxcontrib-redoc.
 docutils # Tooling for RST processing and the swagger extension.
 Jinja2 # Requires investigation. Possibly inherited from previous repo with a custom theme.
 PyYaml # Requires investigation. Possibly used as tooling for swagger API reference content.

docs/docsite/requirements.txt

@@ -8,6 +8,10 @@ alabaster==1.0.0
     # via sphinx
 ansible-pygments==0.1.1
     # via sphinx-ansible-theme
+attrs==25.4.0
+    # via
+    #   jsonschema
+    #   referencing
 babel==2.16.0
     # via sphinx
 certifi==2024.8.30
@@ -27,6 +31,11 @@ jinja2==3.1.4
     # via
     #   -r docs/docsite/requirements.in
     #   sphinx
+    #   sphinxcontrib-redoc
+jsonschema==4.26.0
+    # via sphinxcontrib-redoc
+jsonschema-specifications==2025.9.1
+    # via jsonschema
 markupsafe==3.0.2
     # via jinja2
 packaging==24.2
@@ -36,9 +45,21 @@ pygments==2.18.0
     #   ansible-pygments
     #   sphinx
 pyyaml==6.0.2
-    # via -r docs/docsite/requirements.in
+    # via
+    #   -r docs/docsite/requirements.in
+    #   sphinxcontrib-redoc
+referencing==0.37.0
+    # via
+    #   jsonschema
+    #   jsonschema-specifications
 requests==2.32.3
     # via sphinx
+rpds-py==0.30.0
+    # via
+    #   jsonschema
+    #   referencing
+six==1.17.0
+    # via sphinxcontrib-redoc
 snowballstemmer==2.2.0
     # via sphinx
 sphinx==8.1.3
@@ -48,6 +69,7 @@ sphinx==8.1.3
     #   sphinx-notfound-page
     #   sphinx-rtd-theme
     #   sphinxcontrib-jquery
+    #   sphinxcontrib-redoc
 sphinx-ansible-theme==0.10.3
     # via -r docs/docsite/requirements.in
 sphinx-notfound-page==1.0.4
@@ -66,7 +88,15 @@ sphinxcontrib-jsmath==1.0.1
     # via sphinx
 sphinxcontrib-qthelp==2.0.0
     # via sphinx
+sphinxcontrib-redoc==1.6.0
+    # via -r docs/docsite/requirements.in
 sphinxcontrib-serializinghtml==2.0.0
     # via sphinx
+typing-extensions==4.15.0
+    # via referencing
 urllib3==2.2.3
     # via requests
+
+# The following packages are considered to be unsafe in a requirements file:
+setuptools==80.9.0
+    # via -r docs/docsite/requirements.in

docs/docsite/rst/index.rst

@@ -18,9 +18,11 @@ Ansible AWX helps teams manage complex multi-tier deployments by adding control,
    contributor/DJANGO_REQUIREMENTS
    contributor/API_REQUIREMENTS
 
+
 .. toctree::
    :maxdepth: 2
    :caption: Developers
 
    rest_api/index
+   open_api/index
 

docs/docsite/rst/open_api/explorer.rst

@@ -0,0 +1 @@
+:orphan:

docs/docsite/rst/open_api/index.rst

@@ -0,0 +1,10 @@
+===================
+AWX OpenAPI Schema 
+===================
+
+This document describes the OpenAPI 3.0.3 specification for the AWX API (version v2).
+
+This schema serves as the complete API documentation and contract for interacting programmatically with AWX, which is used for managing Ansible automation workflows, inventories, credentials, and job execution.
+
+* `Explore the AWX OpenAPI Schema <explorer.html>`_
+* `Download the AWX OpenAPI Schema <https://s3.amazonaws.com/awx-public-ci-files/awx/devel/schema.json>`_

docs/docsite/rst/rest_api/_swagger/download-json.py

@@ -1,13 +0,0 @@
-import requests
-
-url = "https://awx-public-ci-files.s3.amazonaws.com/community-docs/swagger.json"
-swagger_json = "./docs/docsite/rst/rest_api/_swagger/swagger.json"
-
-response = requests.get(url)
-
-if response.status_code == 200:
-    with open(swagger_json, 'wb') as file:
-        file.write(response.content)
-    print(f"JSON file downloaded to {swagger_json}")
-else:
-    print(f"Request failed with status code: {response.status_code}")

sonar-project.properties

@@ -77,7 +77,9 @@ sonar.exclusions=\
     **/*.pyd,\
     **/build/**,\
     **/dist/**,\
-    **/*.egg-info/**
+    **/*.egg-info/**,\
+    **/download-json.py,\
+    docs/docsite/conf.py
 
 # =============================================================================
 # COVERAGE EXCLUSIONS

tox.ini

@@ -36,5 +36,5 @@ deps =
   -r{toxinidir}/docs/docsite/requirements.in
   -c{toxinidir}/docs/docsite/requirements.txt
 commands =
-  python {toxinidir}/docs/docsite/rst/rest_api/_swagger/download-json.py
+  python {toxinidir}/docs/docsite/download-json.py
   sphinx-build -T -E -W -n --keep-going {tty:--color} -j auto -c docs/docsite -d docs/docsite/build/doctrees -b html docs/docsite/rst docs/docsite/build/html