hackforla / hackforla/peopledepot

Add OpenAPI (swagger) docs to our documentation

Open
#239 13 comments 0 reactions 0 assignees View on GitHub
complexity: medium draft feature: docs: PD team documentation PII: FALSE ready for dev lead role: dev ops s: CTJ s: hackforla.org s: kb s: PD team s: VRMS size: 3pt
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

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.