Autogenerated docs for REST API

[bpmct]

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.

@mtojek:

Track progress

OSS

/api/v2:

• / docs: api root, buildinfo, csp #5493
• /csp/reports docs: api root, buildinfo, csp #5493
• /buildinfo docs: api root, buildinfo, csp #5493
• /updatecheck docs: api root, buildinfo, csp #5493
• /config/deployment docs: audit, deploymentconfig, files, parameters #5506
• /audit and /audit/testgenerate docs: audit, deploymentconfig, files, parameters #5506
• /files docs: audit, deploymentconfig, files, parameters #5506
• /parameters docs: audit, deploymentconfig, files, parameters #5506
• /authcheck docs: applications and authorization #5477
• /applications docs: 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

• feat: Validate swagger definitions #5694

UI improvements

• docs: improve authentication page #5567 Authentication page: explain how a user can generate tokens, link with automation page

Other

• docs: update swaggo/swag v1.8.9 #5590

[kylecarbs]

The godoc reference has a pretty nice view too!

[Emyrk]

At some point we'll have to nail down our apis and version them properly

[bpmct]

GitLab has nice auto-generated documentation for their CLI as well. https://glab.readthedocs.io/en/latest/completion/index.html

[github-actions]

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]

Looking into this

[mtojek]

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]

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.

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.

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

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 😢

func (c *Client) Upload(ctx context.Context, contentType string, content []byte) (UploadResponse, error) {

[mtojek]

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]

Ok, time for part 2.

will implement a linter/validator. In the end, we could detect outdated undocumented API functions, wrong HTTP methods, and missing fields in request entities.

plus document other API methods.