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.
My goals:
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.
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.
Awesome! Here is a direct link to the bookmarks API output so people can see what a fully documented API endpoint looks like, since many of the others are still pretty sparse.
It would be really helpful if the table of contents page had a bit more of a description of what each API does, and not just the list of URLs, because it can otherwise be difficult to tell what they all do.
Thanks so much for this Ned, it’s a great step forward.
Braden, thanks. I see what you mean about the table of contents page. It’s already got the “summary” listed, though many endpoints don’t currently provide one. To add more than that, we’d have to display the “description” which could be quite long. Or do you have a different idea?
Maybe your suggestion amounts to, “endpoints should include a good one-line summary”?
This is a great step forward! At first I didn’t quite understand what you were trying to achieve, but having a static online API documentation is a blessing for the community. Thanks for your work! Now we need a documentation hackathon to fill the blanks
