API Improvements

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

- [ ] https://github.com/openedx/edx-platform/issues/32610
- [ ] https://github.com/openedx/edx-platform/issues/35057
- [ ] Add drf-spectacular to edx-platform
- [x] 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.
- [ ] DEPR Discovery - Should we get rid of api-doc-tools
- [ ] https://github.com/openedx/edx-platform/issues/36157