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

- [ ] 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

[vladimirCampusGovIl]

Hello @feanil, @awais786,

This case is connected to add OpenAPI 3.0 version instead or togetether with Swagger 2.0 version that exist today? If so, when, and in which version of OpenEdX is it planned?

[feanil]

@vladimirCampusGovIl we don't currently have anyone taking this work on so it's not currently planned for a release. If you're interested in helping switch us from drf-yasg to drf-spectacular, let me know and I can help guide you on what needs to be done.