feat: Build framework for generating API docs

[mtojek]

Related: #3522
Preview: link

Changes:

• Expose the swagger doc.json via chi.Router
• Add feature flag for enabling swagger endpoint (disabled by default)
• Write multiple .md docs pages, grouped by tags like Workspaces, Templates, etc.
• Update manifest.json file to include API doc pages

Doc pages are generated from swagger.json using widdershins and a custom, modified template. The widdershins generates a single Markdown file, so scripts/apidocgen/postprocess cuts it into .md files, and updates the manifest.json file.

schemas.md contains all request/response entities linked from other .md files.

Follow-up:

• Add missing // swagger comments to .go files in coderd as this PR has already 30+ files modified
• Write validators to make sure that // swagger comments are inline with chi router

[mtojek]

Thanks for all comments, @mafredri! I guess that I cleared the majority of them. Looking forward to a review from Ben, and if successful, we can get this change in.

[bpmct]

sanity check: New API docs (swagger and markdown) are being generated (and committed) during each release? Is this also how we generate our Prometheus docs?

[mtojek]

Both actions, Prometheus and API docs, use the same target, make gen, so every generated doc is stored in the repository. If you see possible drawbacks, we can sync offline.

[bpmct]

Went through the docs pages and I'm a huge fan of the format! Having the API docs available on our public docs will make it easy to consume & search. And providing sample CURLs is 👌🏼

I'm almost ready to approve but had a few questions related to your follow-up notes:

Add missing // swagger comments to .go files in coderd as this PR has already 30+ files modified

I'm assuming this follow-up PR will add documentation for all of the available routes since the current docs are incomplete. Do you have a sense of how long this will take, and whether we should add a notice in the meantime saying something similar to "this page is incomplete, stay tuned." I don't want it to seem like we only have ~6 API routes

Write validators to make sure that // swagger comments are inline with chi router

Does this mean that, essentially, every API route has to be documented? If so, it will be awesome to share that we have API docs for essentially every use case our dashboard or CLI handles. Of course, with some minor nuances (e.g. create template version, lookup org id, etc).

[mtojek]

Hey @bpmct!

I'm assuming this follow-up PR will add documentation for all of the available routes since the current docs are incomplete. Do you have a sense of how long this will take

It may take a while as we need to cover all routes and model structures, and if you look at coderd and codersdk package we have plenty of them :) I would book 2-3 days to cover those, and address potential suggestions during code reviews.
In the meantime, I'd like to prepare some validation/test to verify that our docs are as much aligned with code as possible.

and whether we should add a notice in the meantime saying something similar to "this page is incomplete, stay tuned." I don't want it to seem like we only have ~6 API routes

Definitely a good idea, I will work on it now.

Does this mean that, essentially, every API route has to be documented? If so, it will be awesome to share that we have API docs for essentially every use case our dashboard or CLI handles. Of course, with some minor nuances (e.g. create template version, lookup org id, etc).

Correct, that's the assumption :)