Skip to content

test: require @Description on published API routes - #31473

Open
nickvigilante wants to merge 2 commits into
mainfrom
vigilante/docs-1439-require-swagger-descriptions
Open

nickvigilante wants to merge 2 commits into
mainfrom
vigilante/docs-1439-require-swagger-descriptions

Conversation

@nickvigilante

@nickvigilante nickvigilante commented Oct 29, 2026 •

Copy link
Copy Markdown
Collaborator

VerifySwaggerDefinitions now fails when a route the REST API reference publishes has no @Description.
The reference renders one page per endpoint from coderd/apidoc/swagger.json, and 363 of the 384 published routes have no description today.

The 363 existing gaps are exempt, so this lands green: AGPL routes in coderd/coderdtest/swaggerdescriptions.go and enterprise routes in enterprise/coderd/coderdenttest/swagger_test.go, sorted by route.
The lists can only shrink.
A listed route fails once it gains a @Description, is hidden with @x-apidocgen {"skip": true}, or no longer has a swagger comment, so each route comes off the list as it's documented.
A new route needs a @Description, or @x-apidocgen {"skip": true} if it isn't published.

The check runs per swagger comment rather than per walked route, so it also covers routes mounted outside /api/v2 (/oauth2/*, /scim/v2/*, /.well-known/*).
The tests now also parse coderd/workspaceapps and enterprise/coderd/legacyscim, so the PTY and SCIM routes are checked; their routes aren't on the walked router, so only the comment-level checks apply to them.

Merge order

#31562, which combines the 35 DOCS-1439 area PRs, adds a @Description to every route on these lists, and #30125 covers the rest.
With the 35 area PRs and #30125 merged into this branch locally, make coderd/apidoc/.gen produced no diff, and both tests passed with both exemption lists empty.
On current main, #31562 and #30125 together describe 386 of 386 published routes.
main added GET and PUT /api/v2/chats/config/advisor after these lists were built, and #31562 describes them too.

So the plan is to merge this PR last and empty both lists in its final commit, which leaves only the rule.
The planned order is #30122 to #30125, then #31562, then #31531, then this PR.
Until then, whichever PRs land first, each test failure names the stale entries to drop.
#30122, #30123, and #30124 add no descriptions.

This PR also adds the requirement to the API guardrails in .claude/docs/WORKFLOWS.md.

Verification

Both tests pass on this branch:

$ go test ./coderd/coderdtest/ -run 'TestEndpointsDocumented|TestSDKFieldsFormatted' -count=1
ok  	github.com/coder/coder/v2/coderd/coderdtest	0.359s
$ go test ./enterprise/coderd/coderdenttest/ -run TestEnterpriseEndpointsDocumented -count=1
ok  	github.com/coder/coder/v2/enterprise/coderd/coderdenttest	0.383s

The exemption counts match swagger.json: 483 swagger comments, 99 hidden, 21 with a description, and 277 + 86 = 363 exempt.

Each failure mode was checked by breaking the code, running the test, and restoring the files byte for byte:

# Removed "get /api/v2/users" from the AGPL list, added "get /api/v2/does-not-exist",
# and gave GET /api/v2/buildinfo a @Description:
get /api/v2/users needs a @Description that says what the route does and when to use it, or @x-apidocgen {"skip": true} if the route is not published
get /api/v2/buildinfo now has a @Description, so remove it from routesWithoutDescription in coderd/coderdtest/swaggerdescriptions.go, or enterpriseRoutesWithoutDescription in enterprise/coderd/coderdenttest/swagger_test.go
get /api/v2/does-not-exist has no swagger comment, so remove it from routesWithoutDescription in coderd/coderdtest/swaggerdescriptions.go, or enterpriseRoutesWithoutDescription in enterprise/coderd/coderdenttest/swagger_test.go

# Ignored @x-apidocgen skip in the parser:
87 failures, one per hidden AGPL route without a description (89 hidden, 2 already described)

# Removed "get /api/v2/licenses" from the enterprise list:
get /api/v2/licenses needs a @Description that says what the route does and when to use it, or @x-apidocgen {"skip": true} if the route is not published

make pre-commit passed through the hook, including lint/go and lint/emdash.
CI runs these tests on Linux, macOS, and Windows; .gitattributes checks files out with LF, and go/scanner strips carriage returns from comments either way.

Plan and decision log

Context

DOCS-1439 audits description coverage in swagger.json and plans one PR per API tag to fill it in, starting with Users, Authorization, Organizations, Members, Builds, Workspaces, and Templates.
The reviewer decided that the existing swagger tests should fail when a route has no description, so new routes stop adding to the backlog while the tag PRs work through it.

Decisions

  • Where the check lives: in VerifySwaggerDefinitions, which both TestEndpointsDocumented and TestEnterpriseEndpointsDocumented call, instead of a new test or a CI script.
  • Per comment, not per route: the router walk only sees /api/v2, but the reference also publishes /oauth2/*, /scim/v2/*, and /.well-known/*.
  • Two exemption lists: the AGPL test parses only AGPL packages, so a single list couldn't detect stale enterprise entries there. The AGPL list is always applied; the enterprise test adds its own with WithSwaggerDescriptionExemptions. Each list is complete against the comments its test parses.
  • Key format: "<method> <route>" with a lowercase method, matching assertUniqueRoutes and the existing subtest names.
  • Sorted by route, then method: entries for one area sit together, so removals are easy to review.
  • Hidden routes: anything with @x-apidocgen {"skip": true} is exempt; other @x-apidocgen values, such as rawBodyFile, don't hide a route.
  • No separate unit test: the endpoint tests are the owning boundary and run on every route change; each failure mode was proven by mutation instead.
  • Out of scope: parameter and schema field descriptions. swaggo already requires text on every @Param, and docs: describe API fields without opening with the Go field name #31531 rewrites the field comments.

Follow-up

#31562 adds descriptions for these routes and leaves these lists alone.
This PR merges last and empties both lists, as described under "Merge order".

Part of DOCS-1439.

Generated by Coder Agents on behalf of @nickvigilante.

The REST API reference renders one page per endpoint from
coderd/apidoc/swagger.json, and 363 of the 384 routes it publishes have
no @description. VerifySwaggerDefinitions now requires one on every
route that is not hidden with @x-apidocgen {"skip": true}.

The 363 routes that predate the rule are listed as exemptions, AGPL
routes in coderd/coderdtest and enterprise routes in the enterprise
test. The lists may only shrink: a listed route fails once it gains a
description, is hidden, or no longer exists, so each route is removed
as it is documented.

The tests now also parse coderd/workspaceapps and
enterprise/coderd/legacyscim, so the PTY and SCIM routes are checked.

Part of DOCS-1439.

Assisted-by: AI
@linear-code

linear-code Bot commented Oct 29, 2026

Copy link
Copy Markdown

DOCS-1439

This was referenced Oct 29, 2026
…drails

Part of DOCS-1439.

Assisted-by: AI

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant