hackforla / hackforla/peopledepot
Add OpenAPI (swagger) docs to our documentation
- Dominant language
- Python
- Stars
- 14
- Forks
- 37
- Avg merge
- 9d 15h
- Merged PRs (30d)
- 5
Description
### Dependency
- #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 #185 for completion
### Resources/Instructions
1. Potential plugins (need redoc rather than swagger)
- [mkdocs-swagger-ui-tag](https://github.com/blueswen/mkdocs-swagger-ui-tag)
- [mkdocs-render-swagger-plugin](https://github.com/bharel/mkdocs-render-swagger- plugin)
- [mkdocs-openapi](https://github.com/Vikash-Kothary/mkdocs-openapi)
- [OpenAPI Docs](https://www.neoteroi.dev/mkdocs-plugins/web/oad/)
- [mkdocs-swagger-ui](https://github.com/byrnereese/mkdocs-swagger-ui)
1. [Instructions on how to access the OpenAPI docs on the server](https://github.com/hackforla/peopledepot/wiki/Cognito-authentication-workflow-(pre-deployment))
### 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.
Contributor guide
Assessment
This issue has not been assessed yet.