Add docs index view and move Swagger to /docs/swagger/#902
Add docs index view and move Swagger to /docs/swagger/#902TheRealHaoLiu wants to merge 2 commits intoansible:develfrom
Conversation
|
This will be more-affecting of aap-gateway. Looks fine to me, but I think you need that team to review. |
AlanCoding
requested review from
huffmanca,
jeffh-oss,
john-westcott-iv and
tznamena
|
I pulled this down and it works as advertised but will require changes to the gateway so we will need a PR for that or a JIRA to track the work. We also need a JIRA for this work effort to get the DVCS check to start working. |
huffmanca
left a comment
huffmanca
left a comment
There was a problem hiding this comment.
I don't see a technical issue with this, and am approving it for now (but note that my approval in DAB means nothing). I don't feel comfortable approving the URL endpoint change for the team, and I'll let the Gateway representatives to DAB provide comments from that front.
|
Also, given that this is a thing, AWX doesn't have its ducks in a row either. I put up ansible/awx#16204 We just need to be more clear on the separations of responsibilities. But 👍 to the plan, just needs paperwork and the full set of cascading changes it implies. |
TheRealHaoLiu
force-pushed
the
docs-reorg
branch
from
30d3a0a to
2c29ac6
Compare
|
Introduces DocsRootView to provide an index of API documentation endpoints at /docs/. Updates URL patterns to include /docs/swagger/, /docs/redoc/, and /docs/schema/. Documentation updated to reflect new endpoints.
Introduces tests to verify accessibility and correctness of API documentation endpoints, including root docs, Swagger UI, and ReDoc. Ensures endpoints are accessible without authentication and return expected data.
john-westcott-iv
force-pushed
the
docs-reorg
branch
from
2c29ac6 to
c180ab7
Compare
|
DVCS PR Check Results: Could not find JIRA key(s) in PR title, branch name, or commit messages |
|
No actionable comments were generated in the recent review. 🎉 ℹ️ Recent review infoConfiguration used: Organization UI Review profile: CHILL Plan: Pro Cache: Disabled due to data retention organization setting Knowledge base: Disabled due to 📒 Files selected for processing (4)
📝 WalkthroughWalkthroughThe changes introduce a new API documentation root view that indexes available documentation endpoints alongside URL configuration reorganization to support dedicated routes for documentation features and raw schema exposure. Changes
Estimated code review effort🎯 2 (Simple) | ⏱️ ~12 minutes 🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches
🧪 Generate unit tests (beta)
Comment |
![cursor[bot]](https://avatars.githubusercontent.com/in/1210556?s=60&v=4){kind=small}
| data['swagger'] = get_relative_url('swagger-ui') | ||
| data['redoc'] = get_relative_url('redoc') | ||
| data['schema'] = get_relative_url('schema') | ||
| return Response(data) |
There was a problem hiding this comment.
Docs root bypasses default auth settings
Medium Severity
DocsRootView hard-codes permission_classes = [permissions.AllowAny], which can override a deployment’s default DRF permission policy and make /docs/ publicly accessible even when the rest of the API (and possibly the docs endpoints) are intended to require authentication.
|
@TheRealHaoLiu we need a JIRA ticket to associate this work with to get the last test passing. Once you have that you can alter the title to say "[AAP-XXXXX] ...." and then do a no-op push and the test will go green. Also, are you coordinating with the components to make sure any component PRs are in place to support this? |
|
5 participants
Description
What is being changed?
/docs/serves as an index page listing available documentation endpoints, rather than directly showing Swagger UI./docs/to/docs/swagger/DocsRootViewthat returns a DRF-style JSON response with links to swagger, redoc, and schema endpoints.Why is this change needed?
/docs/went directly to Swagger UI while/docs/redoc/and/docs/schema/were nested under it. This was confusing for API consumers.How does this change address the issue?
/docs/serves as a proper index/root endpoint that lists all available documentation options, making the URL hierarchy more intuitive and discoverable.Type of Change
Self-Review Checklist
Testing Instructions
Prerequisites
ansible_base.api_documentationenabledSteps to Test
python manage.py runserver/api/v1/docs//api/v1/docs/swagger/and verify Swagger UI loads/api/v1/docs/redoc/and verify ReDoc loads/api/v1/docs/schema/and verify the OpenAPI schema is returnedExpected Results
/api/v1/docs/returns JSON:{"swagger": "/api/v1/docs/swagger/", "redoc": "/api/v1/docs/redoc/", "schema": "/api/v1/docs/schema/"}/api/v1/docs/swagger/displays Swagger UI/api/v1/docs/redoc/displays ReDoc/api/v1/docs/schema/returns OpenAPI schemaAdditional Context
Required Actions
/api/v1/docs/expecting Swagger UI will need to update to/api/v1/docs/swagger/Note
Medium Risk
Changes public API documentation routes (notably moving Swagger off
/docs/), which may break consumers that hardcode the old URL; logic changes are otherwise small and covered by new tests.Overview
Reworks API documentation routing so
GET /docs/is now a new unauthenticated JSON index (DocsRootView) linking to Swagger, ReDoc, and the OpenAPI schema.Moves Swagger UI from
/docs/to/docs/swagger/while keeping/docs/redoc/and/docs/schema/intact, and updates docs plus adds tests asserting the new endpoints and index response.Written by Cursor Bugbot for commit c180ab7. This will update automatically on new commits. Configure here.
Summary by CodeRabbit
New Features
Documentation