Add x-ai-description to schema

[fosterseth]

SUMMARY

Adding ansible_base.api_documentation to the INSTALL_APPS extends the schema to include an AI friendly description to each endpoint

get full list if endpoints, action, and description here https://gist.github.com/fosterseth/99d71c20ca1ddeb042ef7d179d3e5fc1
e.g.

        "/api/v2/jobs/{id}/": {
            "get": {
                "operationId": "jobs_retrieve",
                "description": "Special handling when deleting a running unified job object.",
                "parameters": [
                    {
                        "in": "path",
                        "name": "id",
                        "schema": {
                            "type": "string",
                            "pattern": "^[0-9]+$"
                        },
                        "required": true
                    }
                ],
                "tags": [
                    "jobs"
                ],
                "responses": {
                    "200": {
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/JobDetail"
                                }
                            }
                        },
                        "description": ""
                    }
                },
                "x-ai-description": "Retrieve single job"
            },
            "delete": {
                "operationId": "jobs_destroy",
                "description": "Special handling when deleting a running unified job object.",
                "parameters": [
                    {
                        "in": "path",
                        "name": "id",
                        "schema": {
                            "type": "string",
                            "pattern": "^[0-9]+$"
                        },
                        "required": true
                    }
                ],
                "tags": [
                    "jobs"
                ],
                "responses": {
                    "204": {
                        "description": "No response body"
                    }
                },
                "x-ai-description": "Delete existing job"
            }
        },

ISSUE TYPE

• New or Enhanced Feature

COMPONENT NAME

• API

---

Note

Augments API schema with AI-friendly descriptions and resource purpose metadata across endpoints and enables schema generation via ansible_base.api_documentation.

• Schema/Documentation:
  • Add x-ai-description via extend_schema_if_available to numerous API endpoints (GET/POST/OPTIONS), including analytics, bulk, debug, inventory, jobs, webhooks, etc.
  • Introduce resource_purpose on view classes to describe endpoint intent.
  • Add ansible_base.api_documentation to INSTALLED_APPS to extend OpenAPI generation.
  • Analytics: add skip_ai_description for disallowed GET mixin; include AI descriptions on proxy views.
• API Views (minor adjustments):
  • Expose get() in GenericCancelView (no behavioral change) and sprinkle small doc-related decorators across many views.

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

[cursor]

Bug: Missing django-ansible-base extra for api_documentation

The 'ansible_base.api_documentation' app is added to INSTALLED_APPS, but the corresponding extra is not included in the django-ansible-base package specification in requirements/requirements_git.txt. This will cause Django to fail with an import error when trying to load the application. The api-documentation (or api_documentation) extra must be added to the django-ansible-base requirements specification.

 

[fosterseth]

doesn't seem relevant

[AlanCoding]

...I think you could, but @Jaapis already added the drf-spectacular dependency, which is what that would indirectly get you

[fosterseth]

@pb82
the default generated x-ai-descriptions are hit or miss, with maybe 50% being OKAY

some problematic entries I noticed

bad parsing on "activity_stream" and other endpoints with a "_"

e.g. /api/v2/ad_hoc_commands/{id}/activity_stream/

generated description is "List all stream for an ad_hoc_command". It should say "List all activity stream.." instead

for whatever reason the description will drop the part that comes before "_"

another example,
`/api/v2/job_templates/{id}/access_list/ => List all list for job_template

some root APIs

/api/v2/bulk
/api/v2/analytics

these are just root entry points to futher endpoints, but the description says something along the lines of "Retrieve single analytic" which is not correct

action related endpoints like cancel, relaunch, health_check, copy, delete, approve, deny

the action oriented endpoints don't have good descriptions out of the box

E.g. /api/v2/credentials/{id}/copy/ => Retrieve single copy for a credential

I fixed up some of the POSTs for launch and relaunch, but not the GET descriptions, e.g. "Retrieve single launch for a system_job_template"

api/v2/me

"List all me" lol

other descriptions that are wrong

/api/v2/job_templates/{id}/bitbucket_dc/ => Create new dc for a job_template
(same with github, etc)
/api/v2/metrics/ => Retrieve single metric
/api/v2/mesh_visualizer/

[pb82]

@fosterseth here is the list of endpoints and their generated description: https://gist.github.com/pb82/cebb9f540383630a0fc85cefc8f46c2c

[pb82]

And here is the special requirement for credentials create: https://gist.github.com/pb82/cebb9f540383630a0fc85cefc8f46c2c#file-gistfile1-txt-L271

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

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

See analysis details on SonarQube Cloud