- Notifications
You must be signed in to change notification settings - Fork929
feat: Build framework for generating API docs#5383
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to ourterms of service andprivacy statement. We’ll occasionally send you account related emails.
Already on GitHub?Sign in to your account
Uh oh!
There was an error while loading.Please reload this page.
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
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 :) |
Uh oh!
There was an error while loading.Please reload this page.
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.jsonusingwiddershins 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