feat: Build framework for generating API docs #5383
Conversation
|
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. |
| # Mark all generated files as fresh so make thinks they're up-to-date. This is | ||
| # used during releases so we don't run generation scripts. |
There was a problem hiding this comment.
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?
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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).
|
Hey @bpmct!
It may take a while as we need to cover all routes and model structures, and if you look at
Definitely a good idea, I will work on it now.
Correct, that's the assumption :) |
Related: #3522
Preview: link
Changes:
doc.jsonviachi.Router.mddocs pages, grouped by tags like Workspaces, Templates, etc.manifest.jsonfile to include API doc pagesDoc pages are generated from
swagger.jsonusing widdershins and a custom, modified template. Thewiddershinsgenerates a single Markdown file, soscripts/apidocgen/postprocesscuts it into.mdfiles, and updates themanifest.jsonfile.schemas.mdcontains all request/response entities linked from other.mdfiles.Follow-up:
// swagger commentsto.gofiles incoderdas this PR has already 30+ files modified// swagger commentsare inline with chi router