Repository navigation
Closed
Labels
docsArea: coder.com/docsArea: coder.com/docs
Description
Currently, you can examine ./codersdk to see the various REST API queries supported by Coder. If you're interested in official documentation for the REST API (like similar to our approach for Coder Classic), please leave upvote this issue or contact us.
Track progress
OSS
/api/v2:
-
/docs: api root, buildinfo, csp #5493 -
/csp/reportsdocs: api root, buildinfo, csp #5493 -
/buildinfodocs: api root, buildinfo, csp #5493 -
/updatecheckdocs: api root, buildinfo, csp #5493 -
/config/deploymentdocs: audit, deploymentconfig, files, parameters #5506 -
/auditand/audit/testgeneratedocs: audit, deploymentconfig, files, parameters #5506 -
/filesdocs: audit, deploymentconfig, files, parameters #5506 -
/parametersdocs: audit, deploymentconfig, files, parameters #5506 -
/authcheckdocs: applications and authorization #5477 -
/applicationsdocs: applications and authorization #5477 -
/workspaceagents(~11 methods) docs: API workspace agents and builds #5538 -
/workspacebuilds/{workspacebuild}(~5 methods) docs: API workspace agents and builds #5538 -
/workspaces(~9 methods) feat: Build framework for generating API docs #5383 docs: API workspace agents and builds #5538 -
/templates/{template}(~7 methods) feat: Build framework for generating API docs #5383 docs: API templateversions, templates, members, organizations #5546 -
/templateversions/{templateversion}(~11 methods) docs: API templateversions, templates, members, organizations #5546 -
/organizations(~12 methods) feat: Build framework for generating API docs #5383 docs: API templateversions, templates, members, organizations #5546 -
/users(~23 methods) docs: API users #5620
Enterprise
/api/v2: #5625
-
/entitlements(1 method) -
/replicas(2 methods) -
/licenses(4 methods) -
/organizations/{organization}/groups(3 methods) -
/organizations/{organization}/provisionerdaemons(2 methods) -
/groups/{group}(3 methods) -
/workspace-quota(1 method) -
/service-banner/appearance(2 methods) -
/scim/v2(6 methods)
Validation
UI improvements
- docs: improve authentication page #5567 Authentication page: explain how a user can generate tokens, link with automation page
Other
Metadata
Metadata
Assignees
Labels
docsArea: coder.com/docsArea: coder.com/docs
Activity
kylecarbs commentedon Aug 15, 2022
The godoc reference has a pretty nice view too!
Emyrk commentedon Aug 16, 2022
At some point we'll have to nail down our apis and version them properly
[-]Docs for REST API[/-][+]Docs for CLI and REST API[/+]bpmct commentedon Sep 19, 2022
GitLab has nice auto-generated documentation for their CLI as well. https://glab.readthedocs.io/en/latest/completion/index.html
[-]Docs for CLI and REST API[/-][+]Autogenerated docs for REST API (and CLI?)[/+]github-actions commentedon Nov 19, 2022
This issue is becoming stale. In order to keep the tracker readable and actionable, I'm going close to this issue in 7 days if there isn't more activity.
mtojek commentedon Dec 9, 2022
Looking into this
mtojek commentedon Dec 9, 2022
I checked possible options and unfortunately, the best approach seems to be tagging API operations via Go comments and generating OpenAPI/swagger description with swag.
An alternative approach is the chi-go/docgen (official project?), which is supposed to generate Markdown/Swagger directly from chi Router, but it isn't aware of request/response entities and status codes + it leaves a lot of noise (Recover, Middleware, Logger, Prometheus, etc.).
Once we have the swagger description ready, we can generate the Markdown file with widdershins. I'm not sure about the visual effect, but it looks promissing.
EDIT:
I'm proceeding with the comments approach.
Emyrk commentedon Dec 9, 2022
I would warn about this approach. We did this in v1 and the auto generated SDK's are not ideal. Then the comments and the code go out of sync if you don't use the SDK.
I have used a tool in the past where it looks at the request/response from our unit tests to generate docs. I wonder if we can auto gen this from our SDK, not the routes.
Like maybe from our sdk functions won't be too bad to parse?A lot of edge cases 😢mtojek commentedon Dec 9, 2022
Thanks for the good chat, @Emyrk and @johnstcn! I will go the standard way (
@comment) but will implement a linter/validator. In the end, we could detect outdated undocumented API functions, wrong HTTP methods, and missing fields in request entities.mtojek commentedon Dec 19, 2022
Ok, time for part 2.
plus document other API methods.
[-]Autogenerated docs for REST API (and CLI?)[/-][+]Autogenerated docs for REST API[/+]