# REST API docs tooling pull request

**URL:** <https://discuss.openedx.org/t/rest-api-docs-tooling-pull-request/92>\
**Category:** Development\
**Created:** [July 24, 2019, 8:40pm UTC](https://discuss.openedx.org/t/rest-api-docs-tooling-pull-request/92 "2019-07-24T20:40:10Z")\
**Posts on this page:** 5\
**Page:** 1

<div class="post-metadata">

**Author:** ![nedbat](https://sea2.discourse-cdn.com/flex020/user_avatar/discuss.openedx.org/nedbat/32/3317_2.png) [@nedbat](https://discuss.openedx.org/u/nedbat)\
**Post date:** [July 24, 2019, 8:40pm UTC](https://discuss.openedx.org/t/rest-api-docs-tooling-pull-request/92/1 "2019-07-24T20:40:10Z")

</div>

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

---

<div class="post-metadata">

**Author:** ![pdpinch](https://sea2.discourse-cdn.com/flex020/user_avatar/discuss.openedx.org/pdpinch/32/36_2.png) [@pdpinch](https://discuss.openedx.org/u/pdpinch)\
**Post date:** [July 30, 2019, 11:39am UTC](https://discuss.openedx.org/t/rest-api-docs-tooling-pull-request/92/2 "2019-07-30T11:39:45Z")

</div>

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

---

<div class="post-metadata">

**Author:** ![nedbat](https://sea2.discourse-cdn.com/flex020/user_avatar/discuss.openedx.org/nedbat/32/3317_2.png) [@nedbat](https://discuss.openedx.org/u/nedbat)\
**Post date:** [August 5, 2019, 9:02pm UTC](https://discuss.openedx.org/t/rest-api-docs-tooling-pull-request/92/3 "2019-08-05T21:02:18Z")

</div>

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](http://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…)

---

<div class="post-metadata">

**Author:** ![jill](https://sea2.discourse-cdn.com/flex020/user_avatar/discuss.openedx.org/jill/32/3188_2.png) [@jill](https://discuss.openedx.org/u/jill)\
**Post date:** [August 6, 2019, 4:02am UTC](https://discuss.openedx.org/t/rest-api-docs-tooling-pull-request/92/4 "2019-08-06T04:02:27Z")

</div>

> [@pdpinch](#):
>
> I think I need some more context.

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](https://pr21207.sandbox.opencraft.hosting/register)  
or [login](https://pr21207.sandbox.opencraft.hosting/login) as a demo user, e.g. `staff@example.com` / `edx` or `honor@example.com` / `edx`.
2. [https://pr21207.sandbox.opencraft.hosting/api-docs/](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`](https://pr21207.sandbox.opencraft.hosting/api-docs/#operations-api-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.

---

<div class="post-metadata">

**Author:** ![nedbat](https://sea2.discourse-cdn.com/flex020/user_avatar/discuss.openedx.org/nedbat/32/3317_2.png) [@nedbat](https://discuss.openedx.org/u/nedbat)\
**Post date:** [August 19, 2019, 9:04pm UTC](https://discuss.openedx.org/t/rest-api-docs-tooling-pull-request/92/5 "2019-08-19T21:04:42Z")

</div>

I started another topic: [Improved API documentation](https://discuss.openedx.org/t/improved-api-documentation/318)
