[FC-0118] docs: add ADR for standardizing API documentation and schema coverage#38189
Open
Abdul-Muqadim-Arbisoft wants to merge 2 commits intoopenedx:docs/ADRs-axim_api_improvementsfrom
Open
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
docs/decisions/0027-standardize-api-documentation-and-schema-coverage.rst
Outdated
Show resolved
Hide resolved
feanil
reviewed
Mar 24, 2026
| """Create a new discussion topic.""" | ||
| return Response({"detail": "Topic created"}, status=201) | ||
|
|
||
| Consequences |
Contributor
There was a problem hiding this comment.
Currently we use https://github.com/openedx/api-doc-tools/ as a shim over drf-yasg, which is currently being used to generate API docs in the platform. Another option here would be to update that tool to replace the underlying drf-yasg usage with drf-spectacular. This would mean that all the endpoints we have currently documented would not need new documentation or further updates. If that is not viable, then I think a consequence would be the deprecation and archival of api-doc-tools and drf-yasg and if that's the direction you want to move then you should document that here.
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
3 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