Publish open api spec on AWX for community use

[tvo318]

SUMMARY

Publish link to open api spec on AWX for community use.

ISSUE TYPE

• Bug, Docs Fix or other nominal change

COMPONENT NAME

• Docs

---

Note

Introduces OpenAPI (v3) documentation to the AWX docs and wires it into the build.

• Integrates sphinxcontrib.redoc in conf.py and configures redoc to render rst/open_api/schema.json at open_api/explorer
• Adds docs/docsite/download-json.py to fetch swagger.json and the OpenAPI schema.json; replaces old per-swagger script and updates tox docs command to run it
• Adds rst/open_api/ pages and links them from index.rst
• Updates docs metadata (copyright year, pubdateshort)
• Updates requirements.in and regenerated requirements.txt with ReDoc and deps

^{Written by Cursor Bugbot for commit 4632d60. This will update automatically on new commits. Configure here.}

[oraNod]

@tvo318 and @thedoubl3j FYI I opened a bug related to the schema while taking a look at this: #16222

[oraNod]

@tvo318 I would advocate for using a sphinx extension that can render the OpenAPI spec in human readable form. I've been playing around with it and think sphinxcontrib-redoc is a pretty good option: https://sphinxcontrib-redoc.readthedocs.io/en/stable/

(We could use sphinxcontrib-openapi instead but the experience is not as nice imho.)

Here is an example from my fork: https://oranod-ansible.readthedocs.io/projects/awx/en/latest/open_api/explorer.html

[tvo318]

I love it. As long as we can fetch changes during a build, that would be easiest to maintain, I good with making it human-readable.

[oraNod]

Now that I've been playing around with the docs, it makes a lot more sense to put this under developers instead. In my fork, I put the OpenAPI spec under the REST API docs like this: https://oranod-ansible.readthedocs.io/projects/awx/en/latest/open_api/index.html

[tvo318]

Yes good thinking!

[oraNod]

Oh, I also just noticed that the schema has this email address. Is this intended for community feedback? Maybe a pointer to the issues list in this repo would be better?

[tvo318]

@tvo318 and @thedoubl3j FYI I opened a bug related to the schema while taking a look at this: #16222

The missing reference is already an issue in Jira that I’m actually assigned to. Let's keep this for transparency to the community.

[tvo318]

Oh, I also just noticed that the schema has this email address. Is this intended for community feedback? Maybe a pointer to the issues list in this repo would be better?

I'm not sure, let me check with that team.
TVo: That email is purely for calendar invites for team meetings it should not be used for community feedback

[cursor]

Warning filter uses wrong category for deprecation warnings

Low Severity

The warnings.filterwarnings call uses category=UserWarning to suppress pkg_resources deprecation warnings, but pkg_resources emits DeprecationWarning not UserWarning. This mismatch means the filter won't catch the intended warnings and they'll still appear in build output. The category parameter needs to be DeprecationWarning for the suppression to work as the comment indicates.

 

[oraNod]

During sphinx-build I see this:

/home/dnaro/git/awx/.tox/docs/lib/python3.14/site-packages/sphinxcontrib/redoc.py:18: UserWarning: pkg_resources is deprecated as an API. See https://setuptools.pypa.io/en/latest/pkg_resources.html. The pkg_resources package is slated for removal as early as 2025-11-30. Refrain from using this package or pin to Setuptools<81.
  import pkg_resources

[sonarqubecloud]

Quality Gate failed

Failed conditions
0.0% Coverage on New Code (required ≥ 80%)

See analysis details on SonarQube Cloud