Repository navigation
test: require @Description on published API routes - #31473
Open
nickvigilante wants to merge 2 commits into
Open
nickvigilante wants to merge 2 commits into
nickvigilante wants to merge 2 commits into
Conversation
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
This was referenced Oct 29, 2026
…drails Part of DOCS-1439. Assisted-by: AI
This was referenced Oct 29, 2026
nickvigilante
marked this pull request as ready for review
November 2, 2026 19:27
This branch has not been deployed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
VerifySwaggerDefinitionsnow 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.goand enterprise routes inenterprise/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/workspaceappsandenterprise/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
@Descriptionto 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/.genproduced no diff, and both tests passed with both exemption lists empty.On current
main, #31562 and #30125 together describe 386 of 386 published routes.mainaddedGETandPUT /api/v2/chats/config/advisorafter 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:
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:
make pre-commitpassed through the hook, includinglint/goandlint/emdash.CI runs these tests on Linux, macOS, and Windows;
.gitattributeschecks files out with LF, andgo/scannerstrips carriage returns from comments either way.Plan and decision log
Context
DOCS-1439 audits description coverage in
swagger.jsonand 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
VerifySwaggerDefinitions, which bothTestEndpointsDocumentedandTestEnterpriseEndpointsDocumentedcall, instead of a new test or a CI script./api/v2, but the reference also publishes/oauth2/*,/scim/v2/*, and/.well-known/*.WithSwaggerDescriptionExemptions. Each list is complete against the comments its test parses."<method> <route>"with a lowercase method, matchingassertUniqueRoutesand the existing subtest names.@x-apidocgen {"skip": true}is exempt; other@x-apidocgenvalues, such asrawBodyFile, don't hide a route.@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.