Skip to content

fix: correct invalid and nonexistent Swagger parameters - #30124

Merged
nickvigilante merged 5 commits into
mainfrom
fix-swagger-params
Nov 5, 2026
Merged

nickvigilante merged 5 commits into
mainfrom
fix-swagger-params

Conversation

@nickvigilante

@nickvigilante nickvigilante commented Sep 29, 2026 •

Copy link
Copy Markdown
Collaborator

Several parameter annotations produced a wrong or invalid spec.

  • GET /api/v2/settings/idpsync/available-fields and field-values documented a required organization path parameter that their URLs do not contain. The annotations were copied from the organization-scoped routes.
  • format(uuid) on the ids array query parameter of the provisioner jobs and daemons routes put format: uuid on the array rather than its items. swag cannot set an item format, so the description now says the IDs are UUIDs.
  • Swagger 2.0 does not allow example on header parameters, which failed strict validation. The Authorization and Content-Disposition examples move to x-example vendor extensions, which Swagger 2.0 allows on parameters and the docs generator uses for the curl samples.
  • TestSwaggerParametersValid reads every path in the generated spec and fails on a non-body parameter with example, an array parameter with format, or a path parameter missing from its route.

Part of DOCS-1122, split from #30121.


🤖 Built with AI assistance.

@linear-code

linear-code Bot commented Sep 29, 2026

Copy link
Copy Markdown

DOCS-1122

@nickvigilante
nickvigilante marked this pull request as ready for review September 29, 2026 20:05
@matifali
matifali removed their request for review October 1, 2026 05:23
@nickvigilante
nickvigilante requested a review from matifali October 1, 2026 21:00
@matifali
matifali removed their request for review October 2, 2026 12:48
@nickvigilante nickvigilante added the api Area: HTTP API label Oct 5, 2026
@matifali
matifali removed their request for review October 14, 2026 18:35
@nickvigilante

Copy link
Copy Markdown
Collaborator Author

/coder-agents-review

@coder-agents-review

coder-agents-review Bot commented Oct 29, 2026 •

Copy link
Copy Markdown
Contributor

Chat: Review posted | View chat
Requested: 2026-10-29 03:11 UTC by @nickvigilante

Review history
  • R1 (2026-10-29): 9 reviewers, 1 Nit, 4 P3, 1 P4, COMMENT. Review
  • R2 (2026-10-29): 9 reviewers, 2 Nit, 5 P3, 1 P4, COMMENT. Review
  • R3 (2026-10-29), 2 Nit, 5 P3, 1 P4, COMMENT. Review
  • R4 (2026-10-29): 10 reviewers, 3 Nit, 6 P3, 4 P4, COMMENT. Review
  • R5 (2026-10-29): 11 reviewers, 3 Nit, 6 P3, 4 P4, APPROVE. Review

deep-review v0.13.0 | Round 5 | 2255794..5231f8c

Last posted: Round 5, 13 findings (6 P3, 4 P4, 3 Nit), APPROVE. Review

Finding inventory

Finding inventory: PR #30124

Findings

# Sev Status Location Summary Round Reviewer Posted
CRF-1 P3 Author fixed (7714daf) docs/reference/api/chats.md:1432 Chat file upload curl sample now sends Content-Disposition: string, rejected by server R1 Netero Yes
CRF-2 P3 Author fixed (7714daf) docs/reference/api/enterprise.md:5303 OAuth2 revoke curl sample now sends Authorization: string, no Basic credential R1 Netero Yes
CRF-3 P3 Author fixed (6adfbe2, c7fe1df) enterprise/coderd/idpsync.go:754 No check catches any of the three fixed annotation classes (path param not in URL, header example, array format) R1 Netero P3, Ryosuke P3, Bisky P3, Meruem P3, Chopper P4, Mafuuu Note Yes
CRF-4 P3 Dropped by orchestrator (merged into CRF-3, same missing regression check) coderd/provisionerjobs.go:76 No check rejects header example or array format R1 Ryosuke, Chopper, Mafuuu No
CRF-5 P4 Author fixed (7714daf) coderd/exp_chats.go:6871 Content-Disposition example drops filename quotes; unquoted form fails for names with spaces R1 Mafuuu, Gon, Leorio, Chopper Yes
CRF-6 P3 Author fixed (7714daf) coderd/provisionerdaemons.go:26 Daemons ids described as job IDs; handler filters on daemon IDs R1 Mafuuu, Gon, Leorio Yes
CRF-7 Nit Author fixed (c7fe1df) coderd/oauth2.go:192 The two rewritten header descriptions phrase the example differently R1 Gon, Leorio Yes
CRF-8 OOS Out of scope (body) coderd/exp_chats.go:7246 Workspace file upload Content-Disposition has no example; curl sample sends string and is rejected R1 Netero, Gon, Leorio No
CRF-9 OOS Out of scope (body) coderd/provisionerdaemons.go:27 Daemons status documented with job statuses; handler parses daemon statuses R1 Mafuuu, Gon, Leorio, Meruem No
CRF-10 OOS Out of scope (body) coderd/provisionerdaemons.go:19-30 Daemons offline and max_age query params undocumented R1 Mafuuu, Gon, Leorio No
CRF-11 OOS Out of scope (body) coderd/provisionerjobs.go:77 Duplicate status enum on provisionerjobs and provisionerdaemons still fails Swagger 2.0 validation R1 Meruem P3, Bisky No
CRF-12 OOS Out of scope (body) coderd/provisionerjobs.go:77 Jobs status documented as one string; handler accepts comma-separated list R1 Meruem No
CRF-13 Note Note (body) PR description Commit body is only "Part of DOCS-1122"; squash commit should carry the PR description R1 Leorio No
CRF-14 Note Dropped by orchestrator (confirmation, asks no change) coderd/apidoc/swagger.json:1 No other instances of the three fixed classes remain in the spec R1 Ryosuke, Pariston No
CRF-15 Note Dropped by orchestrator (confirmation, asks no change) coderd/provisionerjobs.go:76 Array format is wrong meaning, not a Swagger 2.0 schema violation; ids change has no server effect R1 Bisky, Chopper No
CRF-16 Nit Author fixed (6adfbe2) coderd/exp_chats.go:6871 Content-Disposition description names the value twice, "file name" and "filename" R2 Gon P2, Leorio Nit Yes
CRF-17 P3 Author fixed (PR description edit) coderd/exp_chats.go:6871 PR description says the examples moved into descriptions; they moved to x-example R2 Leorio P3, Gon Note, Knov Note Yes
CRF-18 P3 Author fixed (5231f8c) coderd/coderdtest/swaggerparser.go:341 Reverse path-param check runs only for routes chi.Walk yields under /api/v2; /api/experimental and other annotations unchecked R4 Ryosuke P3, Mafuuu P3, Knov P3, Meruem Note, Zoro Note Yes
CRF-19 P4 Author fixed (5231f8c) coderd/coderdtest/swagger_test.go:59 Test doc comment says Swagger 2.0 rejects array format; the schema allows it R4 Gon P2, Chopper P4, Leorio P4, Zoro P4, Ryosuke Nit, Mafuuu Nit Yes
CRF-20 Nit Author fixed (5231f8c) coderd/coderdtest/swaggerparser.go:341 New comment restates the loop below it R4 Gon P2 Yes
CRF-21 P4 Author fixed (5231f8c) coderd/coderdtest/swagger_test.go:86 Array format failure message names no fix, unlike the example message R4 Gon P4, Leorio P4 Yes
CRF-22 P4 Author fixed (5231f8c) coderd/coderdtest/swaggerparser.go:338 assertPathParametersDefined now checks both directions; name describes one R4 Gon P4 Yes
CRF-23 P4 Dropped by orchestrator (two anonymous decode structs with different fields; sharing a type couples two independent tests to save about 10 lines) coderd/coderdtest/swagger_test.go:65 Second copy of anonymous swagger struct and ReadDoc unmarshal R4 Zoro No
CRF-24 OOS Out of scope (body) coderd/coderdtest/swaggerparser.go:171 VerifySwaggerDefinitions runs no annotation checks for routes outside the walked APIHandler, skipped experimental routes, or @router comments that match no route R4 Bisky, Meruem, Mafuuu No
CRF-25 Nit Dropped by orchestrator (comment is accurate and mostly substantive; the restating clause is one short phrase, and this comment was already reworded once at the review's request) coderd/coderdtest/swagger_test.go:59 TestSwaggerParametersValid doc comment partly restates the test name and the path assertion R5 Gon P2 No
CRF-26 Nit Dropped by orchestrator (the trailing period came from the review's own CRF-16 suggested text; no reader impact) coderd/exp_chats.go:6871 Content-Disposition description ends with a period, unlike most single-sentence @PARAM descriptions R5 Gon No
CRF-27 OOS Out of scope (body) coderd/exp_chats.go:7246 Workspace file upload Content-Disposition description words the same header differently from line 6871 R5 Gon No

Contested and acknowledged

CRF-3 (P3, enterprise/coderd/idpsync.go:754) - No check catches the three fixed annotation classes

  • Finding: Nothing fails when a path @Param is absent from the @Router URL (assertPathParametersDefined checks only router to @Param), when a header param has example, or when an array param has format. Proposed: add the reverse path-param check in coderd/coderdtest/swaggerparser.go and a test over coderd/apidoc/swagger.json that fails on non-body example and array format.
  • Author defense (R2, PRRC_kwDOGkVX1s8AAAABBr52QA): Not changing in this PR. The reverse path-param check and a swagger.json example/format lint are new test infrastructure that could surface other existing violations, beyond this annotation-only fix. The duplicate status enum also keeps full spec validation failing. Better as a follow-up. No ticket linked.
  • Panel re-raised (R2, 0/6 accept): Netero, Ryosuke, Bisky, Meruem, Chopper, and Mafuuu, each the same agent that raised it in R1, re-raised. Each ran a scan of coderd/apidoc/swagger.json at 7714daf over 762 parameters and found 0 path params missing from their URL, 0 non-body params with example, and 0 array params with format, so the checks surface no other existing violations. The duplicate status enum (CRF-11) blocks only full validate.Spec, not these targeted checks. Orchestrator reproduced the scan (762 params, 0 violations). If the author still declines, a human must file a ticket or accept the gap.

Law analysis

Not run. Effective additions 4 (threshold 1000).

Round log

Round 1

Full panel (round 1). Netero first pass: 3 P3, no P0, panel proceeded. Panel: ging-go, ryosuke (Go specialists), pariston, mafuuu (core), gon, leorio (once-per-PR floor), bisky (tested annotation behavior via TestEndpointsDocumented), chopper (API contract), meruem (wildcard). Mafu-san omitted to stay within the focused size target. Findings: 4 P3, 1 P4, 1 Nit posted; 5 out of scope; 1 Note (body); 2 Notes dropped as confirmations; CRF-4 merged into CRF-3. Meruem's duplicate-enum P3 moved to out of scope because the PR does not change the status lines. Reviewed against 2255794..e74d2c8.

Round 2

Fix round (only fixes to prior findings; no files added, no signature changes, effective LOC unchanged). Churn guard PROCEED: CRF-1, CRF-2, CRF-5, CRF-6, CRF-7 addressed; CRF-3 contested. Netero rerun via its R1 agent (contested). Panel: dispute check-in via R1 agents for ryosuke, bisky, meruem, chopper, mafuuu; new agents for ging-go (Go files changed), gon and leorio (annotation comment lines changed), knov (wildcard). CRF-3 re-raised by all six raisers (0/6 accept). CRF-7 re-raised: fix left Authorization description repeating its x-example (Gon P2, Meruem Nit, Knov Nit, Leorio Nit; set Nit. Keep-argument for P2: the two copies of the credential can drift and the table would disagree with the curl sample. It loses because the value is a fixed placeholder and the cost is docs wording only.) New: CRF-16 Nit (Gon P2. Keep-argument: the two spellings may read as two values. It loses because the sentence says plainly that one header carries one filename.), CRF-17 P3 (Leorio P3 over Gon/Knov Note: squash commit carries the stale bullet). Leorio's alternative for CRF-7 (add example to Content-Disposition description) conflicts with the author's report that escaped quotes break swag; majority fix posted. Reviewed against e74d2c8..7714daf.

Round 3 update

BLOCKED. CRF-7 silent (no reply or change after the R2 re-raise; its thread stayed resolved because the R2 unresolve failed with an integration permission error, so the author may not have seen it). CRF-3 (reverse path-param check only), CRF-16, CRF-17 claimed fixed; not verified by a panel this round. No review panel. Reviewed against: 7714daf..6adfbe2.

Round 4

Fix round (commits 6adfbe2 and c7fe1df address prior findings; no files added, no exported signature change, effective additions +43 since R2). Churn guard PROCEED: CRF-3, CRF-7, CRF-16, CRF-17 addressed. Netero (new agent): no findings, verified CRF-3 and CRF-7 by mutation. Panel (new agents): ryosuke, bisky, meruem, chopper, mafuuu (CRF-3 raisers), gon, leorio, knov (CRF-7/16/17 raisers; gon and leorio also for new comments), ging-go (Go files), zoro (wildcard). Orchestrator verified by mutation: restoring the idpsync organization param fails TestEnterpriseEndpointsDocumented; restoring base docs.go fails TestSwaggerParametersValid on the four fixed params. All prior posted findings verified fixed. New: CRF-18 P3 (the reverse check sits in the per-route chi.Walk callback, so annotations outside /api/v2 are unchecked; three reviewers reproduced; extends the placement the R1 comment proposed). CRF-19 P4: Gon rated P2; keep-argument: a reader may expect a spec validator to catch array format and treat the test as redundant. It loses because the cost is a wrong comment in a test with no runtime or CI effect. CRF-20 Nit: Gon P2; keep-argument: AGENTS.md requires substantive comments. It is a convention violation, which is the Nit definition. CRF-22 P4 kept: if the loop stays in assertPathParametersDefined the name misdescribes it; moot if CRF-18 moves the loop. CRF-23 dropped: keep-argument was that a third test would add a third copy; it loses because the structs decode different fields and sharing couples independent tests. Reviewed against 7714daf..c7fe1df.

Round 5

Fix round (5231f8c moves the path-param check into TestSwaggerParametersValid and reverts swaggerparser.go; 2 files). Churn guard PROCEED: CRF-18 to CRF-22 addressed. Netero (new agent): no findings. Panel (new agents): ryosuke, mafuuu, knov, meruem, zoro, gon, chopper, leorio (R4 raisers), ging-go (Go files), bisky (test changed), razor (wildcard). All R4 findings verified fixed; Knov, Chopper, Leorio, Bisky mutated docs.go with a stray path param on an /api/experimental and an idpsync route and saw the test fail. Orchestrator verified: base docs.go fails TestSwaggerParametersValid on all six fixed params; head passes TestSwaggerParametersValid, TestEndpointsDocumented, TestEnterpriseEndpointsDocumented. CRF-25 dropped: Gon P2. Keep-argument: AGENTS.md requires substantive, concise comments, and one clause restates the assertion. It loses because the comment states two facts the code does not (Swagger 2.0 example rule, swag array format behavior), and it was already rewritten once at the review's request. CRF-26 dropped: keep-argument is that the period diverges from about 95 percent of @PARAM descriptions; it loses because the review's own CRF-16 text introduced it and the rendered table is unaffected in meaning. CRF-27 OOS. No open findings. Reviewed against c7fe1df..5231f8c.

About deep-review

CRF = Coder Review Finding (P0-P4, Nit, Note)

Reviewer Focus
Bisky tests
Chopper ops/errors
Churn-guard change verification
Ging language modernization
Gon naming
Hisoka edge cases
Killua perf
Kite change integrity
Knov contracts
Knuckle SQL
Komugi flake/determinism
Kurapika security
Law decomposition
Leorio docs
Luffy product
Mafu-san process
Mafuuu contracts
Melody dispatch/pairing
Meruem structural
Nami frontend
Netero mechanical checks
Pariston premise testing
Pen-botter product gaps
Razor verification
Robin duplication
Ryosuke Go arch
Takumi concurrency
Zoro shape

🤖 Managed by Coder Agents.

@coder-agents-review coder-agents-review Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This PR removes two nonexistent organization path params from the deployment idpsync routes, moves format(uuid) off the ids array params into the description, and moves two header example(...) values into descriptions. 4 P3, 1 P4, 1 Nit.

Out of scope (needs a ticket or explicit acceptance by a human):

  • coderd/exp_chats.go:7246: POST /api/v2/chats/{chat}/workspace-files documents Content-Disposition with no example, so its curl sample sends Content-Disposition: string and the server rejects it with "Provide a filename via the Content-Disposition header."
  • coderd/provisionerdaemons.go:27: the daemons status param is documented with job statuses (pending, running, ...), but the handler parses daemon statuses (offline, idle, busy), so documented values do not match any daemon.
  • coderd/provisionerdaemons.go:19-30: the handler accepts offline and max_age, and neither has an @Param, so the generated docs omit both filters.
  • coderd/provisionerjobs.go:77 and coderd/provisionerdaemons.go:27: the status enum in swagger.json lists pending through failed twice (type enum plus enums(...)), so both routes still fail Swagger 2.0 validation (enum in body shouldn't contain duplicates from go-openapi/validate).
  • coderd/provisionerjobs.go:77: status is documented as one string, but the handler parses it with p.Strings, which accepts a comma-separated list.

Notes:

  • The only commit body is "Part of DOCS-1122." If the squash commit does not carry the PR description, git blame on these annotations loses the Swagger 2.0 reason for moving the examples into descriptions.

🤖 This review was automatically generated with Coder Agents.

Comment thread docs/reference/api/chats.md Resolved
Comment thread docs/reference/api/enterprise.md Resolved
Comment thread enterprise/coderd/idpsync.go Resolved
Comment thread coderd/exp_chats.go Resolved
Comment thread coderd/provisionerdaemons.go Resolved
Comment thread coderd/oauth2.go Resolved
Add x-example values for the Content-Disposition and Authorization
header parameters so the generated curl samples stay valid, and
correct the provisioner daemons ids description.

Part of DOCS-1122.

Assisted-by: AI
@nickvigilante

Copy link
Copy Markdown
Collaborator Author

/coder-agents-review

@coder-agents-review coder-agents-review Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Round 2 of the review of the Swagger parameter fixes: 1 P3 and 1 Nit are new, and 1 P3 and 1 Nit from round 1 are re-raised.

The curl sample examples, the quoted filename, and the daemon ids description are fixed and verified at 7714daf. The missing regression check is re-raised because the checks find no existing violations in the current spec. If it stays out of this PR, it needs a linked ticket or a human decision to accept the gap; an unlinked follow-up is not tracked anywhere.

🤖 This review was automatically generated with Coder Agents.

Comment thread coderd/exp_chats.go Resolved
Comment thread coderd/exp_chats.go Resolved
Make TestEndpointsDocumented fail when an @PARAM path name is not a
{name} segment in the @router, so a stray copied path parameter cannot
return. Also tighten the Content-Disposition description.

Part of DOCS-1122.

Assisted-by: AI
@nickvigilante

Copy link
Copy Markdown
Collaborator Author

/coder-agents-review

@coder-agents-review coder-agents-review Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Round 3: the review panel did not run, because one finding from round 2 has no reply or change.

The Authorization description at coderd/oauth2.go:192 still ends with For example, `Basic Y2xpZW50X2lkOmNsaWVudF9zZWNyZXQ=`. while extensions(x-example=...) sets the same value, and Content-Disposition now carries its example only in x-example. The round 2 re-raise is a reply in a thread that stayed marked resolved, so it may not have been visible. Delete the sentence and run make gen, or reply in that thread with why it should stay.

The new reverse path-param check, the Content-Disposition wording, and the PR description edit will be verified in the next panel round. The regression check finding also asked for a check on header example and array format; 6adfbe2 adds only the path-param check, and the panel will judge whether that resolves it.

🤖 This review was automatically generated with Coder Agents.

Add TestSwaggerParametersValid to fail on non-body parameters with an
example and on array parameters with a format. Drop the duplicate
Authorization example from its description now that x-example carries it.

Part of DOCS-1122.

Assisted-by: AI
@nickvigilante

Copy link
Copy Markdown
Collaborator Author

/coder-agents-review

@coder-agents-review coder-agents-review Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Round 4 of the review of the Swagger parameter fixes. Every earlier finding is verified fixed at c7fe1df. 1 P3, 3 P4, and 1 Nit are new, all in the two new checks.

Both new checks fail when the bug they guard is put back: re-adding the idpsync organization param fails TestEnterpriseEndpointsDocumented, and restoring the base docs.go fails TestSwaggerParametersValid on the four fixed parameters. The P3 is about where the path-parameter check runs. The fix that the first review proposed puts it inside the per-route walk, and that walk never reaches /api/experimental.

Out of scope (needs a ticket or explicit acceptance by a human):

  • coderd/coderdtest/swaggerparser.go:171: VerifySwaggerDefinitions runs its annotation checks only for routes that chi.Walk yields under APIHandler. Annotations for /api/experimental, /oauth2, /scim/v2, /api/v2/workspaceagents/me/experimental/, and @Router comments that match no registered route get no route, security, accept, or path-parameter check.

🤖 This review was automatically generated with Coder Agents.

Comment thread coderd/coderdtest/swaggerparser.go Resolved
Comment thread coderd/coderdtest/swaggerparser.go Resolved
Comment thread coderd/coderdtest/swaggerparser.go Resolved
Comment thread coderd/coderdtest/swagger_test.go Resolved
Comment thread coderd/coderdtest/swagger_test.go Resolved
Move the stray path parameter check into TestSwaggerParametersValid so
it covers every route in the generated spec, including experimental
routes the router walk never reaches, and revert the router-walk
version. Clarify the format and example messages.

Part of DOCS-1122.

Assisted-by: AI
@nickvigilante

Copy link
Copy Markdown
Collaborator Author

/coder-agents-review

@coder-agents-review coder-agents-review Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Round 5 of the review of the Swagger parameter fixes: no new findings. Every finding from rounds 1 to 4 is verified fixed at 5231f8c.

TestSwaggerParametersValid now reads every path in the generated spec. With the base docs.go restored, it fails on all six parameters this PR fixes. A stray path parameter added to an /api/experimental route also fails it. At head it passes, and so do TestEndpointsDocumented and TestEnterpriseEndpointsDocumented.

Out of scope (needs a ticket or explicit acceptance by a human):

  • coderd/exp_chats.go:7246: the workspace file upload describes Content-Disposition as "Filename of the file (attachment; filename=...)", while the chat file upload at line 6871 describes the same header differently.
  • The out-of-scope items listed in the round 1 and round 4 reviews are still open and still need a ticket or acceptance.

🤖 This review was automatically generated with Coder Agents.

@nickvigilante
nickvigilante merged commit 6de3d92 into main Nov 5, 2026
33 checks passed
@nickvigilante
nickvigilante deleted the fix-swagger-params branch November 5, 2026 19:22
@github-actions github-actions Bot locked and limited conversation to collaborators Nov 5, 2026
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.

Labels

api Area: HTTP API

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants