[FC-0118] docs: add ADR for standardizing API documentation and schema coverage#38189
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
docs/decisions/0027-standardize-api-documentation-and-schema-coverage.rst
Outdated
Show resolved
Hide resolved
| """Create a new discussion topic.""" | ||
| return Response({"detail": "Topic created"}, status=201) | ||
|
|
||
| Consequences |
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.
There was a problem hiding this comment.
Thanks for flagging this, you're right that the ADR doesn't address api-doc-tools
One concern with upgrading the shim to use drf-spectacular under the hood is that drf-yasg is largely unmaintained at this point and has notable limitations with OpenAPI 3.0 support, which is part of the motivation for moving to drf-spectacular in the first place. Also worth noting that even if we swap the internals, we'd still be committing to maintaining api-doc-tools as a wrapper indefinitely, it would need to keep up with drf-spectacular's API over time, which is ongoing effort with not a lot of upside once the migration is done.
That said, I want to make sure I'm not dismissing the upgrade path without properly investigating it. I'll do an R&D to check the feasibility of replacing drf-yasg inside api-doc-tools with drf-spectacular, and update the ADR based on findings. If it's viable and the maintenance burden is acceptable, that's clearly the lower-friction path. If not, I'll document the deprecation of api-doc-tools and drf-yasg explicitly as a consequence as you suggested.
3 participants
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