Skip to content

docs: describe the Debug API operations and parameters - #31514

Closed
nickvigilante wants to merge 2 commits into
mainfrom
vigilante/api-descriptions-debug
Closed

nickvigilante wants to merge 2 commits into
mainfrom
vigilante/api-descriptions-debug

Conversation

@nickvigilante

@nickvigilante nickvigilante commented Oct 29, 2026 •

Copy link
Copy Markdown
Collaborator

Describes the five Debug API routes and improves the force and request body parameters, so the REST API reference page for each route has more than a title.
The reference renders from swagger.json, and these routes had no description.

Merge notes

This PR doesn't touch #31473's exemption lists.
If #31473 merges first, TestEndpointsDocumented names each route on this PR to remove from those lists.

Verification

$ python3 check_routes.py <route list>
summary: need=5 problems=0 thin_params_left=0
$ go test ./coderd/coderdtest/ -run 'TestEndpointsDocumented|TestSDKFieldsFormatted' -count=1
$ go test ./enterprise/coderd/coderdenttest/ -run TestEnterpriseEndpointsDocumented -count=1
$ make lint/emdash
ok  	github.com/coder/coder/v2/coderd/coderdtest	1.419s
ok  	github.com/coder/coder/v2/enterprise/coderd/coderdenttest	2.720s
OK: no emdash or endash characters found.

A JSON diff of swagger.json against origin/main changes only description values: 7 in total, all on routes in this PR or their parameters, and no other value differs.

doc-check self-check

Ran the doc-check skill in author self-check mode on the branch diff, one persona at a time: Fact Checker, Continuity Editor, Copy Editor, then Skeptic on what survived. The other personas (Cartographer, Newcomer, Reader Advocate, Architect) didn't run.

  • Fixed, Fact Checker: GET /api/v2/debug/health said sections you dismissed are marked as dismissed, but the handler marks only five of the six sections and skips provisioner_daemons (coderd/debug.go:133-146). The sentence is removed.
  • Skeptic rejected 1: websockets lowercase against WebSocket on other pages (no rule sets the casing).
Claims checked against the code
Route Claim Evidence
All /api/v2/debug/* routes Requires the Owner role (permission to read debug information) coderd/coderd.go:2005 (ResourceDebugInfo read check in the /debug middleware), coderd/rbac/roles.go:422 (Owner gets all permissions except the listed resources, and ResourceDebugInfo isn't listed)
GET /api/v2/debug/health Returns a cached report while it's newer than the healthcheck refresh interval, and force=true runs a new check coderd/debug.go:83-90
PUT /api/v2/debug/health/settings Requires permission to update the deployment configuration, which only the Owner role has (the Auditor role has read only) coderd/debug.go:222, coderd/rbac/roles.go:495
PUT /api/v2/debug/health/settings Returns 204 when the settings don't change coderd/debug.go:263
PUT /api/v2/debug/health/settings Section values are DERP, AccessURL, Websocket, Database, WorkspaceProxy, ProvisionerDaemons codersdk/healthsdk/healthsdk.go:31-36
Writing rules applied
  • One to three sentences per route, present tense, first sentence starts with a verb and stands alone on the endpoint card.
  • Permissions name the built-in roles, traced through api.Authorize calls, middleware, and coderd/rbac/roles.go.
  • Routes without a session token say so, and routes with another credential name it.
  • Streams say that the route upgrades to a WebSocket or sends server-sent events, and what each message carries.
  • Full API paths and literals (fields, parameters, values) are in backticks.
  • Shared parameter wording is copied exactly only where the code matches it.
  • No em dashes, en dashes, semicolons, or raw angle brackets and braces outside backticks.

Annotation notes, not changed here: GET /api/v2/debug/health marks only five of the six sections as dismissed and skips provisioner_daemons (coderd/debug.go:133-146). GET /api/v2/debug/health also accepts a format query parameter (json or text) that isn't annotated, and its error message lists simple instead of text (coderd/debug.go).

Part of DOCS-1439.

Generated by Coder Agents on behalf of @nickvigilante.

The REST API reference renders these routes from swagger.json, and they
had no description. This adds one to each Debug route and improves the
health check parameters.

Part of DOCS-1439.

Assisted-by: AI
Part of DOCS-1439.

Assisted-by: AI
@nickvigilante

Copy link
Copy Markdown
Collaborator Author

Combined into #31562, where this PR's changes are the commit docs: describe the Debug API operations and parameters. The claims table above still covers that commit.

Generated by Coder Agents on behalf of @nickvigilante.

@github-actions github-actions Bot locked and limited conversation to collaborators Oct 30, 2026
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant