API Improvements

[feanil]

Context

The edx-platform repo already generates API documentation via make api-docs. This will generate new API docs at
docs/api/_build/html/index.html

• These docs aren't published anywhere.
• APIs that impact just the calling user and APIs for manipulating the system are intermingled.
• To generate the API docs, the following tools are used:
  • drf-yasg - https://drf-yasg.readthedocs.io/en/stable/
  • sw2sphinxopenapi.py - A custom script in edx-platform to generate RST from an Open API 2.0 spec.
    • https://github.com/openedx/edx-platform/blob/master/docs/sw2sphinxopenapi.py
  • sphinx - The /edx-platform/docs/api sphinx project.
  • api-doc-tools - An openedx github repo that abstracts away some of dry-yasg
    • I'm not sure what value this is providing so we may want to deprecate this.

Open API and drf-yasg

• drf-yasg only supports Open API 2.0 and has no plans for supporting Open API 3.0
• Some teams are already using drf-spectactular to replace drf-yasg.
• drf-spectactular supports Open API 3.0

Tasks

Tasks

Beta Give feedback

1. Publish the current api docs to docs.openedx.org #32610
   +0
   
2. Migrating LMS APIs to DRF #35057
   22 of 45
   epic +1
   
3. Add drf-spectacular to edx-platform
4. Update sw2sphinxopenapi.py to be able to publish openapi 3.0 schema to sphinx. - No longer needed because we use a 3rd party plugin to sphinx that does this.
5. DEPR Discovery - Should we get rid of api-doc-tools
6. Document How to get API keys to start using the API.