Improved API documentation

(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.

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.

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.

2 Likes

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 :stuck_out_tongue:

4 Likes

FYI, sandbox has been rebuilt with the most recent commit from this PR (255d049):

https://pr21207.sandbox.opencraft.hosting/api-docs/

1 Like

I’ve cleaned this up, and would like to merge it. This comment on the PR summarizes things that still need to be figured out, but can be done after merging: https://github.com/edx/edx-platform/pull/21207#issuecomment-532394747

1 Like