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.

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

[drakeredwind01]

Sphinx and the Missing Anchor Issue:

Warnings for Broken Links: Sphinx excels at identifying broken links within your documentation. When an anchor (reference point within a document) no longer exists, Sphinx generates warnings during the build process. This proactive approach helps maintain accurate and up-to-date documentation, a crucial aspect for a complex project like the Linux kernel.
Why Sphinx is Superior to the Alternatives:

Here's how Sphinx compares favorably to the listed options:

mkdocs-swagger-ui-tag & 2. mkdocs-render-swagger-plugin:
These plugins are specifically designed for building API documentation with Swagger/OpenAPI specifications. While useful for API docs, they lack the versatility of Sphinx.

Sphinx can handle various content types beyond APIs, including text, code listings, and images – perfect for the diverse nature of the Linux kernel documentation.
mkdocs-openapi:
Similar to the previous options, mkdocs-openapi caters primarily to API documentation. While it can handle OpenAPI specifications, Sphinx offers broader functionality.

OpenAPI Docs:
OpenAPI Docs likely refers to the official tooling for generating documentation directly from OpenAPI specs. While efficient, it might lack the customization options Sphinx provides.

Sphinx allows tailoring the documentation layout, branding, and inclusion of additional content beyond the pure API specifications.
mkdocs-swagger-ui:
Another plugin focused on API documentation with Swagger UI integration. It falls short of Sphinx's versatility.

BREAKDOWN

	Primary Functionality	Content Types Supported	Link Checking	Customization	Community & Ecosystem	Cross-Platform Support
Sphinx	General Documentation	Text, Code, Images, Tables, etc.	Warns about broken anchors	Extensive customization options (themes, plugins)	Large community, extensive plugins and themes	Yes
mkdocs-swagger-ui-tag	API Documentation (Swagger UI)	OpenAPI Specifications	No	Limited customization	Smaller community, fewer plugins	Yes
mkdocs-render-swagger-plugin	API Documentation (Swagger UI)	OpenAPI Specifications	No	Limited customization	Smaller community, fewer plugins	Yes
mkdocs-openapi	API Documentation (OpenAPI)	OpenAPI Specifications	No	Limited customization	Smaller community, fewer plugins	Yes
OpenAPI Docs	API Documentation (OpenAPI)	OpenAPI Specifications	No	Limited customization	Official tooling, limited community support	Yes
mkdocs-swagger-ui	API Documentation (Swagger UI)	OpenAPI Specifications	No	Limited customization	Smaller community, fewer plugins	Yes

[fyliu]

@drakeredwind01 Sphinx doesn't have the functionality to satisfy the main requirement in this issue which is to generate API docs.

[fyliu]

I think my comment didn't address the context of your topic. My comment was in the context of this issue's requirements: adding OpenAPI docs to our documentation. Your topic is a broader one that we've covered before in this project: documentation generators.
But your comparison is also apples to oranges. Sphinx is a documentation system and the others are MkDocs plugins. Sphinx vs. MkDocs would be the same level comparison.

Note that this project is currently using MkDocs and there's already pages written with MkDocs-specific markup.

For historical context, we've compared documentation generator systems in the past, including Sphinx, Asciidoc, and MkDocs, weighed our needs and organization needs, and settled on MkDocs. I was the one wanting to adopt Sphinx at the time. I have an older documentation site set up here, with this page showing some of the UI enhancements it provides over Github markdown. This is our docs with similar enhancements in MkDocs (some of it still in PR). The organizational needs part was that hackforla needed to choose a system for all its projects, not just for peopledepot, and wanted to link them up in the future. So while Sphinx was slightly better for us as a python project, MkDoc was a much better choice for other projects.

This is why I mentioned ease of integration as a dimension to compare. If it involves adding an entire documentation system or replacing our current one and converting all our existing documentation files to it, that's a big hurdle to integration. If it's an independent generator that just outputs a webpage into the gh-pages branch where the document is hosted, that might be a viable solution. This is why MkDocs plugins are more favored. I was thinking maybe there's some independent generator out there that could also work, but Sphinx is too big a change.

To summarize why we're not going to move to Sphinx from MkDocs

• We've already compared and decided on this
• We need to maintain compatibility with other hackforla projects
• It would require an extra amount of work to do a conversion of our current documentation pages
• This issue requires a much smaller resource investment than this

[fyliu]

@drakeredwind01 are you still working on this issue?

Please provide update

1. Progress: "What is the current status of your project? What have you completed and what is left to do?"
2. Blockers: "Difficulties or errors encountered."
3. Availability: "How much time will you have this week to work on this issue?"
4. ETA: "When do you expect this issue to be completed?"
5. Pictures or links* (if necessary): "Add any pictures or links that will help illustrate what you are working on."

• remember to add links to the top of the issue if they are going to be needed again.

[fyliu]

Confirmed with @drakeredwind01 he's not working on this anymore, so unassigning him.

[fyliu]

After hearing about and really comparing them, I'm now convinced that redoc is the better UI for API docs over swagger. See discussion.

We should try to have a redoc interface in our documentation.

[shmonks]

@fyliu Given our stakeholder-informed decision to go for Redoc rather than Swagger, I think this issue needs to be revised - putting it into Questions/Review for now.