Repository navigation
fix: correct invalid and nonexistent Swagger parameters - #30124
Conversation
Part of DOCS-1122. Assisted-by: AI
a5022c4 to
e74d2c8
Compare
|
/coder-agents-review |
|
Chat: Review posted | View chat Review history
deep-review v0.13.0 | Round 5 | Last posted: Round 5, 13 findings (6 P3, 4 P4, 3 Nit), APPROVE. Review Finding inventoryFinding inventory: PR #30124Findings
Contested and acknowledgedCRF-3 (P3, enterprise/coderd/idpsync.go:754) - No check catches the three fixed annotation classes
Law analysisNot run. Effective additions 4 (threshold 1000). Round logRound 1Full 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 Round 2Fix 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 updateBLOCKED. 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 4Fix 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 Round 5Fix 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-reviewCRF = Coder Review Finding (P0-P4, Nit, Note)
|
There was a problem hiding this comment.
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-filesdocumentsContent-Dispositionwith no example, so its curl sample sendsContent-Disposition: stringand the server rejects it with "Provide a filename via the Content-Disposition header."coderd/provisionerdaemons.go:27: the daemonsstatusparam 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 acceptsofflineandmax_age, and neither has an@Param, so the generated docs omit both filters.coderd/provisionerjobs.go:77andcoderd/provisionerdaemons.go:27: thestatusenum inswagger.jsonlistspendingthroughfailedtwice (type enum plusenums(...)), so both routes still fail Swagger 2.0 validation (enum in body shouldn't contain duplicatesfromgo-openapi/validate).coderd/provisionerjobs.go:77:statusis documented as one string, but the handler parses it withp.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 blameon these annotations loses the Swagger 2.0 reason for moving the examples into descriptions.
🤖 This review was automatically generated with Coder Agents.
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
|
/coder-agents-review |
There was a problem hiding this comment.
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.
|
/coder-agents-review |
There was a problem hiding this comment.
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
|
/coder-agents-review |
There was a problem hiding this comment.
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:VerifySwaggerDefinitionsruns its annotation checks only for routes thatchi.Walkyields underAPIHandler. Annotations for/api/experimental,/oauth2,/scim/v2,/api/v2/workspaceagents/me/experimental/, and@Routercomments that match no registered route get no route, security, accept, or path-parameter check.
🤖 This review was automatically generated with Coder Agents.
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
|
/coder-agents-review |
There was a problem hiding this comment.
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 describesContent-Dispositionas "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.
Several parameter annotations produced a wrong or invalid spec.
GET /api/v2/settings/idpsync/available-fieldsandfield-valuesdocumented a requiredorganizationpath parameter that their URLs do not contain. The annotations were copied from the organization-scoped routes.format(uuid)on theidsarray query parameter of the provisioner jobs and daemons routes putformat: uuidon the array rather than its items. swag cannot set an item format, so the description now says the IDs are UUIDs.exampleon header parameters, which failed strict validation. TheAuthorizationandContent-Dispositionexamples move tox-examplevendor extensions, which Swagger 2.0 allows on parameters and the docs generator uses for the curl samples.TestSwaggerParametersValidreads every path in the generated spec and fails on a non-body parameter withexample, an array parameter withformat, or a path parameter missing from its route.Part of DOCS-1122, split from #30121.
🤖 Built with AI assistance.