search

openedx / api-doc-tools

Tools for writing and generating API documentation for edX REST APIs
Apache License 2.0
5 stars 11 forks source link

Add edx-api-doc-tools to edx-cookiecutters #160

Open jristau1984 opened 1 year ago

jristau1984 commented 1 year ago

The edX API Documentation tools (GitHub, ReadTheDocs) are a flexible and friendly way to incrementally document HTTP APIs, allowing one to start with mostly auto-generated docs, and then use decorators to move towards fully-documented API catalogs.

Our previous strategy for generating API documentation (counting on Swagger to auto-parse the docstrings) is no longer supported.

Currently, at least edx-platform and Registrar use the library. (Registrar counts on the library to generate partner-facing API documentation). The edx-api-doc-tools library should be installed into the edx-cookiecutters so that it is available by default in new Django IDAs.

kdmccormick commented 1 year ago

FYI ~@ned~ @nedbat -- Jeremy copied this out of Jira for us.

I think this would be a good first task for whomever becomes this repository's maintainer. I personally think it would make sense for tCRIL to maintain this repo; when the time comes around I'll pitch it to my team, but I can't make any promises.