REST API docs tooling pull request

Development
1

I’ve been slowly working on a pull request that puts some working API docs tooling into place in edx-platform: https://github.com/edx/edx-platform/pull/21207

I’d love to hear comments about it. It uses drf-yasg and its swagger_auto_schema decorator, with Markdown for descriptions. It publishes both dynamic swagger docs, and static Sphinx-generated docs.

Comments about details of the pull request can go on the pull request. Larger discussion can be here.

5 Likes
2

This is exciting Ned, but I think I need some more context. What will this do once it’s merged?

3

I thought I had explained it on the PR, but I know it’s hard to step back and see it as others do, without the context.

The goal of the PR is to make it possible to document our REST APIs in the Python code, then produce live Swagger docs at a url (/api-docs/) and also static documentation on readthedocs.org.

The PR builds out some of that tooling, and converts two endpoints to new documentation decorators. There are still things to be worked out, especially in how the text mark up is rendered in the live docs and static docs.

(BTW, I’m adding some of this to the PR…)

4

Hi @pdpinch, we’ve set up an OpenCraft sandbox if you want to have a look at the live API docs so far:

  1. https://pr21207.sandbox.opencraft.hosting/register
    or login as a demo user, e.g. staff@example.com / edx or honor@example.com / edx.
  2. https://pr21207.sandbox.opencraft.hosting/api-docs/

The docs still need work to ensure all the parameters are available to the forms, but you can at least see the concept, e.g.

  1. Scroll down to the api_courses_v1_courses_list
  2. Click “Try it Out” to reveal the form that hits the API.
  3. Click “Execute” to run the query.
  4. View the “Server response” box to see the response.

And since you’re logged in, the results shown are specific to you and what you have access to.

1 Like
5

I started another topic: Improved API documentation