[FC-0118] docs: add ADR for standardizing API documentation and schema coverage#38189
Merged
feanil merged 5 commits intoApr 28, 2026
Conversation
- Propose adoption of drf-spectacular across Open edX services - Require @extend_schema decorators for all API endpoints - Document request/response schemas, status codes, and error conditions
Abdul-Muqadim-Arbisoft
changed the title
Faraz32123
reviewed
Mar 19, 2026
feanil
reviewed
Mar 24, 2026
- Add context explaining what api-doc-tools is and its relationship to drf-yasg - Document deprecation and archival of api-doc-tools as a consequence - Add migration guide mapping api-doc-tools decorators and URL helpers to their drf-spectacular equivalents - Add rejected alternative for updating api-doc-tools internals - Add rollout step for final archival cutover Closes review comment by @feanil
feanil
reviewed
Apr 20, 2026
Contributor
feanil
left a comment
feanil
left a comment
There was a problem hiding this comment.
Mostly looks good, I think this is close to merging once we add a little bit more context on the decision to pivot away from api-doc-tools
Contributor
|
@kdmccormick tagging you for review since we've spoken about this before. This can wait till after the release is cut. |
Member
|
Thanks, I'll take a look next week |
…ompatibility analysis Address review feedback on FC-0118 ADR 0027: - Add context paragraph explaining what api-doc-tools is (drf-yasg shim, decorators it provides, schema view, OpenAPI 2.0 output) - Document deprecation of api-doc-tools and drf-yasg as a consequence, including transition-window behavior - Add detailed 8-point incompatibility analysis explaining why drf-yasg cannot be replaced with drf-spectacular inside api-doc-tools (recorded in the ADR itself for future reference) - Add migration plan for existing api-doc-tools consumers with concrete decorator/import/setting mapping - Update Rollout Plan to track api-doc-tools removal - Add references to drf-spectacular migration guide, drf-yasg upstream status, and api-doc-tools repository
feanil
approved these changes
Apr 27, 2026
Contributor
feanil
left a comment
feanil
left a comment
There was a problem hiding this comment.
One small grammer issue (using Open edX as a noun) but otherwise I think this is good to merge now. I don't need to review again once the grammer issue is fixed.
feanil
approved these changes
Apr 28, 2026
Contributor
|
@Abdul-Muqadim-Arbisoft this looks great, please be sure to make the DEPR ticket for dropping api-doc-tools and drf-yasg so we can communicate that out to folks. We'll need to drop it from the other services (credentials, course-discovery, etc at some point as well.) |
feanil
merged commit cb35381
into
openedx:docs/ADRs-axim_api_improvements
65 checks passed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
5 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Description
Currently, API documentation and schema coverage is inconsistent across Open edX services, with many views lacking OpenAPI decorators and machine-readable documentation. This ADR proposes standardizing on drf-spectacular with @extend_schema decorators across all endpoints to improve AI-tool discoverability, reduce duplicate endpoints, and provide a consistent developer experience for external integrations.
Issue: #38164