Add OpenAPI (swagger) docs to our documentation

[fyliu]

Dependency

• Stakeholder engagement: which API documentation UI to use? #388

Overview

Since the project is not yet deployed, non-developers can't see the API docs that are generated on the fly by the backend. We need to generate and add that to our documentation so that everyone can view them.

Action Items

• Implement and evaluate the several different mkdocs plugins for ease of use and integration, OpenAPI 3 support, and look and feel
• Write a Decision Record comparing the options and recommend one
• Create a PR for this issue using the chosen plugin

After Merge

• Check Epic: Transition to MkDocs #185 for completion

Resources/Instructions

1. Potential plugins (need redoc rather than swagger)
   • mkdocs-swagger-ui-tag
   • [mkdocs-render-swagger-plugin](https://github.com/bharel/mkdocs-render-swagger- plugin)
   • mkdocs-openapi
   • OpenAPI Docs
   • mkdocs-swagger-ui
2. Instructions on how to access the OpenAPI docs on the server

More details

To clarify the issue description, the project does generate API docs using drf-spectacular, but it's on the fly only when the server is running. The packages in resources will generate a static version and put it inside the mkdocs site so it becomes part of the documentation separate from the running server.

[fyliu]

Question: I'm not sure what milestone to use for this. Seems like it should be before All Tables Added. I was thinking Compliance, but I looked it up and it doesn't seem to fit there.

Other than that, this is ready to be prioritized.

[drakeredwind01]

Django REST Swagger
https://django-rest-swagger.readthedocs.io/en/latest/
made directly for Django rest framework

[fyliu]

@drakeredwind01 that's the same functionality that drf-spectacular provides. You have to be running the server to view it and it's also not integrated into the mkdocs site we have in ghpages.

What we're hoping for is something like a mkdocs plugin that generates a page for mkdocs with the same information.