Fix API documentation rendering (#15116)

[spaut33]

SUMMARY

This is a fix for #15116

The change addresses the need for better organization and usability in the Swagger/Redoc UI by automatically grouping endpoints into sections by swagger_topic attribute if present, otherwise it uses model's name or fallback to api if nothing above setted in the view. It also respects deprecated attribute.
Introduced CustomSwaggerAutoSchema to handle tagging for views which is globally applied using default settings.

ISSUE TYPE

• Bug, Docs Fix or other nominal change

COMPONENT NAME

• API
• Docs

AWX VERSION

awx: 24.6.2.dev206+g5c84b184e8

ADDITIONAL INFORMATION

API documentation is available in the dev-mode: http://localhost:8013/api/swagger/ and http://localhost:8013/api/redoc/

If merged, the documentation will appear as follows:

[thedoubl3j]

@tvo318 I know there has been some talk around docs and I am not sure what changes (if any) you all had in mind, take a peak whenever you get back.

[AlanCoding]

This appears well thought-out. I started the checks, we want to make sure that the schema check is functioning as normal. Otherwise, I think this is doing a lot of important updates.

Super minor, black awx/api/swagger.py should take care of the lint failure.

[spaut33]

This appears well thought-out. I started the checks, we want to make sure that the schema check is functioning as normal. Otherwise, I think this is doing a lot of important updates.

Super minor, black awx/api/swagger.py should take care of the lint failure.

Thank you for taking your time to view the PR. I'll take care of the lint and tests failures right away.

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[spaut33]

diff failed because the new schema includes tags and deprecated flag while the reference scheme lacks these elements.

[AlanCoding]

^ that's actually fantastic. This is a check which is intended by fail by design, it just lets us know what changed. So that needs to be reviewed to assure intentionality. As you say, looks good.

+++ schema.json	2025-01-03 14:20:43.535814938 +0000
@@ -12421,17 +12421,18 @@
     "contact": {
       "email": "[email protected]"
     },
-    "description": "Test description",
+    "description": "AWX API Documentation",
     "license": {
-      "name": "BSD License"
+      "name": "Apache License"
     },
     "termsOfService": "https://www.google.com/policies/terms/",
-    "title": "Snippets API",
+    "title": "AWX API",
     "version": ""

For what you mention:

   "paths": {
     "/api/": {
       "get": {
+        "deprecated": false,
         "description": "",
         "operationId": "api_list",
         "parameters": [],

And these tags never had any thought go into them before. More specific entries are better.

         },
         "summary": "List supported API versions",
         "tags": [
-          "api"
+          "Versioning"
         ]
       },
       "parameters": []
     },

This actually introduces a lot of new tags, and that's what most of the text volume of the diff shows

         "summary": "Make a GET request to this resource to retrieve the list of",
         "tags": [
-          "api"
+          "Ad Hoc Commands"
         ]
       },

And that seems to cover all types of changes shown there. I was worried about how hard it would be to make this work correctly, but it seems you've already got it.

[oraNod]

This looks good to me and seems like a really solid improvement. Thanks very much @spaut33 🚀