API Documentation Tool

Requirements from Doc Team

• Any tool choices shouldn't affect how and when the documentation team works on docstrings for the endpoint classes. 

• The main priority is having docstrings that are tool independent as much as possible.

History of various tools used at edX

Apiary

• The solutions team (contact: @Matthew Drayer (Deactivated)) has used it during the design phase and for collaboration by multiple editors.

• They have not used it for live documentation for something that is released. That is, it wasn't a publishing tool that read docstrings from code files and published it in independent form.

• Example: http://docs.edxcoursemetadataapi.apiary.io/#

Swagger

• The analytics team (contact: @ClintonB (Deactivated)) has used it for publishing the APIs on the analytics server.  It works with docstrings as we have them, assuming we set up Swagger to be installed with the server module.

• Example: https://stage-edx-analyticsapi.edx.org/docs/

Django Rest Viewer

• APIs created using the Django Rest Framework are automatically published using the django rest viewer. 

• Example: https://courses.edx.org/api/mobile/v0.5/video_outlines/courses/MITx/6.002_4x/3T2014

Table of Options