Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 4 additions & 1 deletion .claude/docs/WORKFLOWS.md
Original file line number Diff line number Diff line change
Expand Up @@ -107,7 +107,10 @@

- Add swagger annotations when introducing new HTTP endpoints. Do this in
the same change as the handler so the docs do not get missed before
release.
release. Every published route needs a `@Description`, directly after
`@Summary`, that says what the route does and when to use it.
`TestEndpointsDocumented` and `TestEnterpriseEndpointsDocumented` fail
without one.
- For user-scoped or resource-scoped routes, prefer path parameters over
query parameters when that matches existing route patterns.
- For experimental or unstable API paths, skip public doc generation with
Expand Down
2 changes: 1 addition & 1 deletion coderd/coderdtest/swagger_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,7 @@ import (
func TestEndpointsDocumented(t *testing.T) {
t.Parallel()

swaggerComments, err := coderdtest.ParseSwaggerComments("..", "../workspaceconnwatcher")
swaggerComments, err := coderdtest.ParseSwaggerComments("..", "../workspaceconnwatcher", "../workspaceapps")
require.NoError(t, err, "can't parse swagger comments")
require.NotEmpty(t, swaggerComments, "swagger comments must be present")

Expand Down
285 changes: 285 additions & 0 deletions coderd/coderdtest/swaggerdescriptions.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,285 @@
package coderdtest

// routesWithoutDescription lists AGPL routes, formatted as "<method> <route>",
// that the API reference publishes without a @Description. They predate the
// requirement in VerifySwaggerDefinitions. Do not add routes here: give a new
// route a @Description, and remove a route from this list when you add one.
var routesWithoutDescription = []string{
"get /.well-known/oauth-authorization-server",
"get /.well-known/oauth-protected-resource",
"get /api/v2/",
"get /api/v2/ai/providers",
"post /api/v2/ai/providers",
"delete /api/v2/ai/providers/{idOrName}",
"get /api/v2/ai/providers/{idOrName}",
"patch /api/v2/ai/providers/{idOrName}",
"get /api/v2/applications/auth-redirect",
"get /api/v2/applications/host",
"get /api/v2/audit",
"get /api/v2/auth/scopes",
"post /api/v2/authcheck",
"get /api/v2/buildinfo",
"get /api/v2/chats",
"post /api/v2/chats",
"get /api/v2/chats/by-workspace",
"get /api/v2/chats/config/auto-archive-days",
"put /api/v2/chats/config/auto-archive-days",
"get /api/v2/chats/config/debug-logging",
"put /api/v2/chats/config/debug-logging",
"get /api/v2/chats/config/debug-retention-days",
"put /api/v2/chats/config/debug-retention-days",
"get /api/v2/chats/config/personal-model-overrides",
"put /api/v2/chats/config/personal-model-overrides",
"get /api/v2/chats/config/plan-mode-instructions",
"put /api/v2/chats/config/plan-mode-instructions",
"get /api/v2/chats/config/system-prompt",
"put /api/v2/chats/config/system-prompt",
"get /api/v2/chats/config/user-debug-logging",
"put /api/v2/chats/config/user-debug-logging",
"get /api/v2/chats/config/user-prompt",
"put /api/v2/chats/config/user-prompt",
"get /api/v2/chats/config/workspace-ttl",
"put /api/v2/chats/config/workspace-ttl",
"post /api/v2/chats/files",
"get /api/v2/chats/files/{file}",
"get /api/v2/chats/watch",
"get /api/v2/chats/{chat}",
"patch /api/v2/chats/{chat}",
"put /api/v2/chats/{chat}/context",
"get /api/v2/chats/{chat}/diff",
"post /api/v2/chats/{chat}/interrupt",
"get /api/v2/chats/{chat}/messages",
"post /api/v2/chats/{chat}/messages",
"patch /api/v2/chats/{chat}/messages/{message}",
"delete /api/v2/chats/{chat}/queue/{queuedMessage}",
"post /api/v2/chats/{chat}/queue/{queuedMessage}/promote",
"post /api/v2/chats/{chat}/reconcile-invalid",
"get /api/v2/chats/{chat}/stream",
"get /api/v2/chats/{chat}/stream/git",
"post /api/v2/chats/{chat}/title/propose",
"post /api/v2/chats/{chat}/tool-results",
"post /api/v2/csp/reports",
"get /api/v2/debug/coordinator",
"get /api/v2/debug/health",
"get /api/v2/debug/health/settings",
"put /api/v2/debug/health/settings",
"get /api/v2/debug/tailnet",
"get /api/v2/deployment/config",
"post /api/v2/deployment/premium-funnel-events",
"get /api/v2/deployment/ssh",
"get /api/v2/deployment/stats",
"get /api/v2/deployment/user-secrets/capabilities",
"get /api/v2/derp-map",
"get /api/v2/experiments",
"get /api/v2/experiments/available",
"get /api/v2/external-auth",
"delete /api/v2/external-auth/{externalauth}",
"get /api/v2/external-auth/{externalauth}",
"get /api/v2/external-auth/{externalauth}/device",
"post /api/v2/external-auth/{externalauth}/device",
"get /api/v2/files/{fileID}",
"get /api/v2/init-script/{os}/{arch}",
"get /api/v2/insights/daus",
"get /api/v2/insights/templates",
"get /api/v2/insights/user-activity",
"get /api/v2/insights/user-latency",
"get /api/v2/insights/user-status-counts",
"post /api/v2/notifications/custom",
"get /api/v2/notifications/dispatch-methods",
"get /api/v2/notifications/inbox",
"put /api/v2/notifications/inbox/mark-all-as-read",
"get /api/v2/notifications/inbox/watch",
"put /api/v2/notifications/inbox/{id}/read-status",
"get /api/v2/notifications/settings",
"put /api/v2/notifications/settings",
"get /api/v2/notifications/templates/custom",
"get /api/v2/notifications/templates/system",
"post /api/v2/notifications/test",
"get /api/v2/oauth2-provider/apps",
"post /api/v2/oauth2-provider/apps",
"delete /api/v2/oauth2-provider/apps/{app}",
"get /api/v2/oauth2-provider/apps/{app}",
"put /api/v2/oauth2-provider/apps/{app}",
"get /api/v2/oauth2-provider/apps/{app}/secrets",
"post /api/v2/oauth2-provider/apps/{app}/secrets",
"delete /api/v2/oauth2-provider/apps/{app}/secrets/{secretID}",
"get /api/v2/oauth2-provider/settings",
"put /api/v2/oauth2-provider/settings",
"get /api/v2/organizations",
"get /api/v2/organizations/{organization}",
"get /api/v2/organizations/{organization}/chats/config/system-prompt",
"put /api/v2/organizations/{organization}/chats/config/system-prompt",
"get /api/v2/organizations/{organization}/chats/models",
"post /api/v2/organizations/{organization}/chats/models",
"get /api/v2/organizations/{organization}/members",
"get /api/v2/organizations/{organization}/members/roles",
"delete /api/v2/organizations/{organization}/members/{user}",
"get /api/v2/organizations/{organization}/members/{user}",
"post /api/v2/organizations/{organization}/members/{user}",
"put /api/v2/organizations/{organization}/members/{user}/roles",
"get /api/v2/organizations/{organization}/members/{user}/workspaces/available-users",
"get /api/v2/organizations/{organization}/paginated-members",
"get /api/v2/organizations/{organization}/provisionerdaemons",
"get /api/v2/organizations/{organization}/provisionerjobs",
"get /api/v2/organizations/{organization}/provisionerjobs/{job}",
"post /api/v2/organizations/{organization}/templates",
"get /api/v2/organizations/{organization}/templates/examples",
"get /api/v2/organizations/{organization}/templates/{templatename}",
"get /api/v2/organizations/{organization}/templates/{templatename}/versions/{templateversionname}",
"get /api/v2/organizations/{organization}/templates/{templatename}/versions/{templateversionname}/previous",
"post /api/v2/organizations/{organization}/templateversions",
"get /api/v2/regions",
"get /api/v2/tailnet",
"get /api/v2/templatebuilder/bases",
"post /api/v2/templatebuilder/compose",
"post /api/v2/templatebuilder/compose/template",
"get /api/v2/templatebuilder/modules",
"post /api/v2/templatebuilder/sessions",
"get /api/v2/templates/examples",
"delete /api/v2/templates/{template}",
"get /api/v2/templates/{template}",
"patch /api/v2/templates/{template}",
"get /api/v2/templates/{template}/daus",
"get /api/v2/templates/{template}/versions",
"patch /api/v2/templates/{template}/versions",
"post /api/v2/templates/{template}/versions/archive",
"get /api/v2/templates/{template}/versions/{templateversionname}",
"get /api/v2/templateversions/{templateversion}",
"patch /api/v2/templateversions/{templateversion}",
"post /api/v2/templateversions/{templateversion}/archive",
"patch /api/v2/templateversions/{templateversion}/cancel",
"post /api/v2/templateversions/{templateversion}/dry-run",
"get /api/v2/templateversions/{templateversion}/dry-run/{jobID}",
"patch /api/v2/templateversions/{templateversion}/dry-run/{jobID}/cancel",
"get /api/v2/templateversions/{templateversion}/dry-run/{jobID}/logs",
"get /api/v2/templateversions/{templateversion}/dry-run/{jobID}/matched-provisioners",
"get /api/v2/templateversions/{templateversion}/dry-run/{jobID}/resources",
"get /api/v2/templateversions/{templateversion}/dynamic-parameters",
"post /api/v2/templateversions/{templateversion}/dynamic-parameters/evaluate",
"get /api/v2/templateversions/{templateversion}/external-auth",
"get /api/v2/templateversions/{templateversion}/logs",
"get /api/v2/templateversions/{templateversion}/parameters",
"get /api/v2/templateversions/{templateversion}/presets",
"get /api/v2/templateversions/{templateversion}/resources",
"get /api/v2/templateversions/{templateversion}/rich-parameters",
"get /api/v2/templateversions/{templateversion}/schema",
"post /api/v2/templateversions/{templateversion}/unarchive",
"get /api/v2/templateversions/{templateversion}/variables",
"get /api/v2/updatecheck",
"get /api/v2/users",
"post /api/v2/users",
"get /api/v2/users/authmethods",
"get /api/v2/users/first",
"post /api/v2/users/first",
"post /api/v2/users/login",
"post /api/v2/users/logout",
"get /api/v2/users/oauth2/github/callback",
"get /api/v2/users/oauth2/github/device",
"get /api/v2/users/oidc-claims",
"get /api/v2/users/oidc/callback",
"post /api/v2/users/otp/change-password",
"post /api/v2/users/otp/request",
"get /api/v2/users/roles",
"post /api/v2/users/validate-password",
"delete /api/v2/users/{user}",
"get /api/v2/users/{user}",
"get /api/v2/users/{user}/ai-provider-keys",
"delete /api/v2/users/{user}/ai-provider-keys/{aiProvider}",
"put /api/v2/users/{user}/ai-provider-keys/{aiProvider}",
"get /api/v2/users/{user}/appearance",
"put /api/v2/users/{user}/appearance",
"post /api/v2/users/{user}/convert-login",
"get /api/v2/users/{user}/gitsshkey",
"put /api/v2/users/{user}/gitsshkey",
"post /api/v2/users/{user}/keys",
"get /api/v2/users/{user}/keys/tokens",
"post /api/v2/users/{user}/keys/tokens",
"get /api/v2/users/{user}/keys/tokens/tokenconfig",
"get /api/v2/users/{user}/keys/tokens/{keyname}",
"delete /api/v2/users/{user}/keys/{keyid}",
"get /api/v2/users/{user}/keys/{keyid}",
"put /api/v2/users/{user}/keys/{keyid}/expire",
"get /api/v2/users/{user}/login-type",
"get /api/v2/users/{user}/notifications/preferences",
"put /api/v2/users/{user}/notifications/preferences",
"get /api/v2/users/{user}/organizations",
"get /api/v2/users/{user}/organizations/{organizationname}",
"put /api/v2/users/{user}/password",
"get /api/v2/users/{user}/preferences",
"put /api/v2/users/{user}/preferences",
"put /api/v2/users/{user}/profile",
"get /api/v2/users/{user}/roles",
"put /api/v2/users/{user}/roles",
"get /api/v2/users/{user}/secrets",
"post /api/v2/users/{user}/secrets",
"post /api/v2/users/{user}/secrets/batch",
"delete /api/v2/users/{user}/secrets/{name}",
"get /api/v2/users/{user}/secrets/{name}",
"patch /api/v2/users/{user}/secrets/{name}",
"put /api/v2/users/{user}/status/activate",
"put /api/v2/users/{user}/status/suspend",
"get /api/v2/users/{user}/workspace/{workspacename}",
"get /api/v2/users/{user}/workspace/{workspacename}/builds/{buildnumber}",
"post /api/v2/workspaceagents/aws-instance-identity",
"post /api/v2/workspaceagents/azure-instance-identity",
"post /api/v2/workspaceagents/google-instance-identity",
"patch /api/v2/workspaceagents/me/app-status",
"get /api/v2/workspaceagents/me/external-auth",
"get /api/v2/workspaceagents/me/gitauth",
"get /api/v2/workspaceagents/me/gitsshkey",
"post /api/v2/workspaceagents/me/log-source",
"patch /api/v2/workspaceagents/me/logs",
"get /api/v2/workspaceagents/me/reinit",
"get /api/v2/workspaceagents/{workspaceagent}",
"get /api/v2/workspaceagents/{workspaceagent}/connection",
"get /api/v2/workspaceagents/{workspaceagent}/containers",
"delete /api/v2/workspaceagents/{workspaceagent}/containers/devcontainers/{devcontainer}",
"post /api/v2/workspaceagents/{workspaceagent}/containers/devcontainers/{devcontainer}/recreate",
"get /api/v2/workspaceagents/{workspaceagent}/containers/watch",
"get /api/v2/workspaceagents/{workspaceagent}/coordinate",
"get /api/v2/workspaceagents/{workspaceagent}/listening-ports",
"get /api/v2/workspaceagents/{workspaceagent}/logs",
"get /api/v2/workspaceagents/{workspaceagent}/pty",
"get /api/v2/workspaceagents/{workspaceagent}/startup-logs",
"get /api/v2/workspacebuilds/{workspacebuild}",
"patch /api/v2/workspacebuilds/{workspacebuild}/cancel",
"get /api/v2/workspacebuilds/{workspacebuild}/logs",
"get /api/v2/workspacebuilds/{workspacebuild}/parameters",
"get /api/v2/workspacebuilds/{workspacebuild}/resources",
"get /api/v2/workspacebuilds/{workspacebuild}/state",
"put /api/v2/workspacebuilds/{workspacebuild}/state",
"get /api/v2/workspacebuilds/{workspacebuild}/timings",
"get /api/v2/workspaces",
"get /api/v2/workspaces/{workspace}",
"patch /api/v2/workspaces/{workspace}",
"delete /api/v2/workspaces/{workspace}/acl",
"get /api/v2/workspaces/{workspace}/acl",
"patch /api/v2/workspaces/{workspace}/acl",
"get /api/v2/workspaces/{workspace}/agent-connection-watch",
"put /api/v2/workspaces/{workspace}/autostart",
"put /api/v2/workspaces/{workspace}/autoupdates",
"get /api/v2/workspaces/{workspace}/builds",
"post /api/v2/workspaces/{workspace}/builds",
"put /api/v2/workspaces/{workspace}/dormant",
"put /api/v2/workspaces/{workspace}/extend",
"delete /api/v2/workspaces/{workspace}/favorite",
"put /api/v2/workspaces/{workspace}/favorite",
"delete /api/v2/workspaces/{workspace}/port-share",
"get /api/v2/workspaces/{workspace}/port-share",
"post /api/v2/workspaces/{workspace}/port-share",
"get /api/v2/workspaces/{workspace}/resolve-autostart",
"get /api/v2/workspaces/{workspace}/timings",
"put /api/v2/workspaces/{workspace}/ttl",
"post /api/v2/workspaces/{workspace}/usage",
"get /api/v2/workspaces/{workspace}/watch",
"get /api/v2/workspaces/{workspace}/watch-ws",
"get /oauth2/authorize",
"post /oauth2/authorize",
"delete /oauth2/clients/{client_id}",
"get /oauth2/clients/{client_id}",
"put /oauth2/clients/{client_id}",
"post /oauth2/register",
"post /oauth2/revoke",
"delete /oauth2/tokens",
"post /oauth2/tokens",
}
Loading
Loading