(I talked about this before, here: REST API docs tooling pull request)
The Open edX code offers a number of REST APIs, but we don’t have docs for them. I have been working on a pull request that adds a basic documentation toolchain for our APIs, and I’d like some feedback before putting much more work into it.
Write documentation for API endpoints in one place, in the code.
Produce a swagger.yaml file that can be used by standard Open API tooling.
Support dynamic Swagger docs served by the running server.
Produce static HTML docs for searching and reference.
I’ve only converted over a couple of docstrings to the new format, in the Bookmarks API: https://github.com/edx/edx-platform/blob/nedbat/api-docs/openedx/core/djangoapps/bookmarks/views.py#L100 Even there, I have not removed all of the pre-existing text describing parameters and responses that can now be provided by drf-yasg.
The current HTML docs can be seen here: https://nedbatchelder.com/files/api_draft/html/gen/index.html (they won’t be published there, this is just for sharing now). Remember that almost none of these endpoints have correctly formatted docs, so the HTML might seem odd for now.
The pull request is here: https://github.com/edx/edx-platform/pull/21207
I’m very interested in your feedback, either here or on the pull request.