Skip to content

fix: document WebSocket routes as 101 responses in the Swagger spec - #30125

Merged
nickvigilante merged 6 commits into
mainfrom
fix-swagger-websocket-responses
Nov 18, 2026
Merged

nickvigilante merged 6 commits into
mainfrom
fix-swagger-websocket-responses

Conversation

@nickvigilante

@nickvigilante nickvigilante commented Sep 29, 2026 •

Copy link
Copy Markdown
Collaborator

Six WebSocket routes were documented as 200 responses: chats/watch, chats/{chat}/stream, chats/{chat}/stream/git, chats/{chat}/stream/parts, workspaces/{workspace}/watch-ws, and workspaceagents/{workspaceagent}/watch-metadata-ws.

Mark them @Success 101, matching the other WebSocket routes, and describe each message. chats/{chat}/stream and stream/parts send a JSON array batch of events per message, so they keep {array}; the others send one event per message.

Also document that the previous template version route returns 204 with no body when there is no previous version.

Part of DOCS-1122, split from #30121.

CI flakes unrelated to this change

On d23267b7c3, two checks failed in code this PR does not touch.


🤖 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:04
@matifali
matifali removed their request for review October 1, 2026 05:22
@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:36
@nickvigilante
nickvigilante force-pushed the fix-swagger-websocket-responses branch from eec236d to 41f1fce Compare October 29, 2026 02:08
@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 02:55 UTC by @nickvigilante

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

deep-review v0.13.0 | Round 4 | 2255794..d23267b

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

Finding inventory

Findings

# Sev Status Location Summary Round Reviewer Posted
CRF-1 P4 Author fixed (a53ea9f) exp_chats.go:9521 stream/parts description omits required client control message R1 Netero Yes
CRF-2 OOS Out of scope (body) workspaceagents.go:807 containers/watch WebSocket route still documented 200 R1 Netero No
CRF-3 OOS Out of scope (body) inboxnotifications.go:122 notifications/inbox/watch WebSocket route still documented 200 R1 Netero, Chopper No
CRF-4 P4 Author fixed (a53ea9f) exp_chats.go:2309 stream/git description omits refresh client message, error messages, and delta semantics R1 Melody, Pariston, Mafuuu, Leorio, Chopper, Razor P4; Kite Note Yes
CRF-5 P3 Author fixed (a53ea9f) workspaces.go:2182 watch-ws description omits event types, data payload, and close on client message R1 Leorio P3; Mafuuu, Chopper Note Yes
CRF-6 P4 Author fixed (a53ea9f) workspaceagents.go:1845 watch-metadata-ws description omits data payload type and close on client message R1 Leorio P4; Mafuuu, Chopper Note Yes
CRF-7 P2 Dropped by orchestrator (restatement is not a defect; Leorio's rewrites keep the sentence) exp_chats.go:292 "Upgrades to a WebSocket." restates summary and 101 row on six routes R1 Gon No
CRF-8 P2 Dropped by orchestrator (accurate; tells clients not to parse a body) templateversions.go:1108 "with no body" repeats 204 R1 Gon No
CRF-9 P2 Dropped by orchestrator (accurate format contract per Chopper, Razor, Melody) exp_chats.go:9521 stream/parts "batch of one or more" while server always sends one event R1 Gon P2; Chopper, Razor Note No
CRF-10 Nit Author fixed (d23267b) workspaces.go:2182 @description placement differs from @Summary-adjacent convention R1 Gon Yes
CRF-11 OOS Out of scope (body) workspaceagents.go:386 follow=true dual-mode routes document no 101 response R1 Melody No
CRF-12 OOS Out of scope (body) swaggerparser.go:306 no check ties WebSocket handlers to @success 101 R1 Pariston No
CRF-13 OOS Out of scope (body) debug.go:299 debug/ws echo WebSocket documented as 201 R1 Razor No
CRF-14 P4 Author fixed (b1e53f2) exp_chats.go:289 chats/watch and chats/{chat}/stream descriptions omit close on client message (CloseRead) R2 Pariston, Razor Yes
CRF-15 P4 Author fixed (b1e53f2) templateversions.go:1108 204 condition belongs in the @success 204 string, not an operation @description R2 Zoro Yes
CRF-16 Nit Author fixed (b1e53f2) exp_chats.go:2306 wire literals in new descriptions are not in backticks R2 Gon Yes
CRF-17 Nit Author fixed (b1e53f2) exp_chats.go:289 one-event-per-message framing worded two ways R2 Gon Yes
CRF-18 OOS Out of scope (body) workspaces.go:2259 sendUpdate sends a zero-value Workspace data event after a conversion error R2 Netero No
CRF-19 Note Note (body) templateversions.go:1107 "precedes" could name the query: newest version of the template created before the named one R4 Zoro No

Contested and acknowledged

Round log

Round 1

Full panel (round 1). Netero first pass: 1 P4, no P0. Panel: ging-go, melody, pariston, mafuuu, leorio, gon, chopper, razor, kite (wildcard, random from distilled set). Focused size target 6-8; 8 selected plus wildcard. 1 P3, 3 P4, 1 Nit posted; 3 dropped (CRF-7, CRF-8, CRF-9); 5 out of scope. Reviewed against 2255794..41f1fce.

Drop gate notes:

  • CRF-7 keep-argument: the sentence repeats the summary and the 101 row on every route. Dropped: no reader consequence, and Leorio's proposed rewrites retain it; for skip routes the description is the only prose in swagger.json.
  • CRF-8 keep-argument: 204 already implies no body. Dropped: the phrase is accurate and harmless; Leorio judged the sentence correct.
  • CRF-9 keep-argument: "batch" suggests multi-event arrays that never arrive. Dropped: the array framing is the wire contract, client ReadEvents decodes arrays, and three reviewers verified the text is accurate.

Round 2

Fix round: a53ea9f only rewrites and moves the PR's own @description lines (no added files, no signature changes, same title, effective LOC unchanged). Churn guard PROCEED: CRF-1, CRF-4, CRF-5, CRF-6, CRF-10 addressed. Panel verified CRF-1, CRF-4, CRF-5, CRF-6 fixed. Netero re-raised the remaining CRF-10 instance at templateversions.go:1108. Panel: melody, pariston, mafuuu, leorio, chopper, razor (raised findings whose code changed), gon (raised CRF-10; comments touched), ging-go (.go files), zoro (wildcard, random from distilled set). New: 2 P4, 2 Nit; 1 out of scope. CRF-15 fix also removes the line CRF-10 flags. Inventory validation: CRF-7, CRF-8, CRF-9 dispositions unaffected by a53ea9f (Gon R2 confirmed no new evidence). Reviewed against 2255794..a53ea9f.

Round 3 update

BLOCKED. CRF-10 silent: no author reply to the R2 re-raise, and b1e53f2 leaves coderd/templateversions.go:1108 after @ID. CRF-14, CRF-15, CRF-16, CRF-17 addressed per churn guard (author claims, not panel-verified). No review panel. Reviewed against 2255794..b1e53f2.

Round 4

Fix round: d23267b moves one @Description line (no added files, no signature changes, same title). Churn guard PROCEED: CRF-10 addressed. Netero: no findings. Panel: pariston, razor (CRF-14), zoro (CRF-15), gon (CRF-10, CRF-16, CRF-17; comments touched), leorio (doc comments touched since R2), ging-go and melody (.go files), meruem (wildcard, random from distilled set). Panel verified CRF-10, CRF-14, CRF-15, CRF-16, CRF-17 fixed; Netero and Melody regenerated the spec with no diff. No new findings; 1 Note (body). Out-of-scope items CRF-2, CRF-3, CRF-11, CRF-12, CRF-13, CRF-18 still need a human decision. Reviewed against 2255794..d23267b.

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 changes six WebSocket routes from @Success 200 to @Success 101, adds a message-framing description to each, and documents the 204 case of the previous template version route. The status codes and framing claims match the handlers, and regenerating the spec produced no diff. Findings: 1 P3, 3 P4, 1 Nit. The P3 and P4 findings are parts of each route's message contract that the new descriptions leave out.

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

  • coderd/workspaceagents.go:807: containers/watch calls websocket.Accept but is still documented @Success 200, so the reference shows 200 for a WebSocket route.
  • coderd/inboxnotifications.go:122: notifications/inbox/watch calls websocket.Accept but is still documented @Success 200, same consequence.
  • coderd/debug.go:299: debug/ws is a WebSocket echo server documented as @Success 201 {object} codersdk.Response.
  • coderd/workspaceagents.go:386: logs?follow=true upgrades to a WebSocket but only 200 is documented; the same applies at coderd/workspacebuilds.go:1034, coderd/templateversions.go:696, coderd/templateversions.go:1978, and coderd/deprecated.go:41. Spec consumers see no 101 for follow mode.
  • coderd/coderdtest/swaggerparser.go:306: no check ties a handler that upgrades to WebSocket to @Success 101, so new WebSocket routes can declare 200 and pass, as the routes above did.

🤖 This review was automatically generated with Coder Agents.

Comment thread coderd/exp_chats.go Resolved
Comment thread coderd/exp_chats.go Resolved
Comment thread coderd/workspaces.go Resolved
Comment thread coderd/workspaceagents.go Resolved
Comment thread coderd/workspaces.go Resolved
Document client messages, event payloads, and delta semantics for the
WebSocket routes, and place each @description directly after @summary.

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.

a53ea9f fixes the stream/parts control message, the stream/git message types, and the watch-ws and watch-metadata-ws payloads; each new sentence matches its handler, and regenerating the spec produced no diff. The @Description move covered the six WebSocket routes but not the previous template version route. New findings: 2 P4, 2 Nit.

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

  • coderd/workspaces.go:2259: when convertWorkspace fails, sendUpdate sends an error event and then, with no return, a data event holding a zero-value codersdk.Workspace, so clients receive the payload this PR now documents but with empty fields.

🤖 This review was automatically generated with Coder Agents.

Comment thread coderd/exp_chats.go Resolved
Comment thread coderd/templateversions.go Resolved
Comment thread coderd/exp_chats.go Resolved
Comment thread coderd/exp_chats.go Resolved
Document that the chat watch and stream routes close on client messages,
use one wording for event framing, wrap literals in backticks, and move
the 204 condition for the previous template version route into its
@success annotation.

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.

b1e53f2 addresses the chat-route close sentence, the 204 condition, the backticks, and the one-event-per-message wording. One finding has no response: the @Description placement re-raised in the previous review. coderd/templateversions.go:1108 still sits after @ID (line 1107) instead of directly after @Summary (line 1106), and the re-raise reply has no answer. Your reply on the 204 finding explains why the @Description line stays, so the fix is to move it up one line, not delete it. Further review is blocked until you move the line or reply on that thread explaining why it should stay where it is.

🤖 This review was automatically generated with Coder Agents.

@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.

d23267b moves the previous template version @Description directly after @Summary, so all seven added descriptions are placed consistently. The fixes from b1e53f2 are verified against the handlers: the close-on-client-message sentence on chats/watch and chats/{chat}/stream, the 204 condition in the @Success 204 string, backticks on wire literals, and the one-event-per-message wording. Regenerating the spec produced no diff. No open findings remain.

The out-of-scope items listed in the earlier reviews still need a ticket or explicit acceptance by a human.

Notes:

  • coderd/templateversions.go:1107: if you want the description exact, GetPreviousTemplateVersion returns the most recently created version of the same template that was created before the named version.

🤖 This review was automatically generated with Coder Agents.

@coder
coder Bot requested review from Emyrk, hwang251 and ibetitsmike November 2, 2026 19:23
@github-actions github-actions Bot added the stale This issue is like stale bread. label Nov 10, 2026
@github-actions github-actions Bot closed this Nov 13, 2026
@nickvigilante nickvigilante reopened this Nov 13, 2026
@nickvigilante
nickvigilante temporarily deployed to main November 13, 2026 16:34 — with GitHub Actions Inactive
@nickvigilante nickvigilante removed the stale This issue is like stale bread. label Nov 13, 2026
@nickvigilante
nickvigilante temporarily deployed to main November 13, 2026 16:34 — with GitHub Actions Inactive
@nickvigilante
nickvigilante temporarily deployed to main November 13, 2026 16:37 — with GitHub Actions Inactive
@nickvigilante
nickvigilante temporarily deployed to docs-preview November 13, 2026 16:41 — with GitHub Actions Inactive
Comment thread coderd/exp_chats.go Outdated
}

// @Summary Watch chat workspace git state via WebSockets
// @Description Upgrades to a WebSocket. Each server message is either a `changes` message with a delta of repository changes since the previous message or an `error` message, and you can send `{"type": "refresh"}` to request an immediate re-scan.

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.

Blocking: since marks time here, and the word-choice rule maps time to after or starting in (Copy Editor)

The sentence reads "a delta of repository changes since the previous message", so a reader cannot tell whether since means time or cause. Rule: docs/.style/style-guide/word-choice.md#choose-words-that-have-one-meaning. This line generates the Description for docs/reference/api/chats.md, so regenerate the API docs after the fix.

Suggested change
// @Description Upgrades to a WebSocket. Each server message is either a `changes` message with a delta of repository changes since the previous message or an `error` message, and you can send `{"type": "refresh"}` to request an immediate re-scan.
// @Description Upgrades to a WebSocket. Each server message is either a `changes` message with a delta of repository changes after the previous message or an `error` message, and you can send `{"type": "refresh"}` to request an immediate re-scan.

Comment thread docs/reference/api/chats.md Outdated

`GET /api/v2/chats/{chat}/stream/git`

Upgrades to a WebSocket. Each server message is either a `changes` message with a delta of repository changes since the previous message or an `error` message, and you can send `{"type": "refresh"}` to request an immediate re-scan.

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.

(Copy Editor) The sentence runs about 32 words, and it packs three message types and a client action into one sentence. Rule: docs/.style/style-guide/voice-and-tone.md#keep-sentences-and-paragraphs-short (a target, not a limit). Split it in the source at coderd/exp_chats.go:2349, and use after as in the blocking comment above:

"Upgrades to a WebSocket. Each server message is either a changes message or an error message. A changes message holds a delta of repository changes after the previous message. You can send {"type": "refresh"} to request an immediate re-scan."

Comment thread coderd/exp_chats.go
}

// @Summary Stream chat events via WebSockets
// @Description Upgrades to a WebSocket and sends each message as a JSON array holding a batch of one or more events. The server closes the connection if you send a message.

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.

(Continuity Editor, Reader Advocate) The JSON array framing is stated twice. The next line, Each WebSocket message is a JSON array of events., already states it, so this clause repeats it. Rule: docs/.style/style-guide/audience-and-scope.md#give-the-audience-only-what-it-needs. Also, message here names a WebSocket frame, while the same page uses message for a chat message.

Suggested change
// @Description Upgrades to a WebSocket and sends each message as a JSON array holding a batch of one or more events. The server closes the connection if you send a message.
// @Description Upgrades to a WebSocket. The server closes the connection if you send a message.

// @Param templateversionname path string true "Template version name"
// @Success 200 {object} codersdk.TemplateVersion
// @Success 204
// @Success 204 "The template version has no previous version"

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.

(Continuity Editor) The Description cell for this 204 row reads "The template version has no previous version", but every other 204 row in docs/reference/ reads "No Content", for example docs/reference/api/chats.md, docs/reference/api/users.md, and docs/reference/api/workspaces.md. A reader comparing responses sees one inconsistent label. Make the Description pattern deliberate across all 204 rows. Do not change only this row. Reverting this row to "No Content" would undo the earlier thread on this line, which moved the reason here on purpose.

@coderagents

coderagents Bot commented Nov 13, 2026

Copy link
Copy Markdown
Contributor

Documentation Check

Blocking

  • docs/reference/api/chats.md (open) - Line 4654, generated from coderd/exp_chats.go:2349: change since to after in "a delta of repository changes since the previous message". Rule: docs/.style/style-guide/word-choice.md#choose-words-that-have-one-meaning.

Findings for agents
- id: language-1
  persona: language
  class: rule
  blocking: true
  file: docs/reference/api/chats.md
  line: 4654
  quote: "a delta of repository changes since the previous message"
  evidence:
    - coderd/exp_chats.go:2349
  rule: docs/.style/style-guide/word-choice.md#choose-words-that-have-one-meaning
  problem: "`since` marks time here, which the rule maps to `after`."
  fix: "Change `since` to `after` at coderd/exp_chats.go:2349 and regenerate the API docs."
  verified: true
- id: language-2
  persona: language
  class: suggestion
  blocking: false
  file: docs/reference/api/chats.md
  line: 4654
  quote: "Each server message is either a `changes` message with a delta of repository changes since the previous message or an `error` message"
  evidence:
    - docs/.style/style-guide/voice-and-tone.md#keep-sentences-and-paragraphs-short
  rule: docs/.style/style-guide/voice-and-tone.md#keep-sentences-and-paragraphs-short
  problem: "The sentence runs about 32 words and packs three message types and a client action."
  fix: "Split the sentence at coderd/exp_chats.go:2349."
  verified: true
- id: consistency-1
  persona: consistency
  class: suggestion
  blocking: false
  file: docs/reference/api/chats.md
  line: 4214
  quote: "Upgrades to a WebSocket and sends each message as a JSON array holding a batch of one or more events."
  evidence:
    - docs/reference/api/chats.md:4216 "Each WebSocket message is a JSON array of events."
  rule: docs/.style/style-guide/audience-and-scope.md#give-the-audience-only-what-it-needs
  problem: "The JSON array framing is stated twice, and `message` names a frame here but a chat message elsewhere on the page."
  fix: "Drop the JSON array clause at coderd/exp_chats.go:3946."
  verified: true
- id: consistency-2
  persona: consistency
  class: suggestion
  blocking: false
  file: docs/reference/api/templates.md
  line: 664
  quote: "The template version has no previous version"
  evidence:
    - docs/reference/api/chats.md:948
    - docs/reference/api/users.md:1023
    - docs/reference/api/workspaces.md:1760
  rule: null
  problem: "This is the only 204 row in docs/reference/ whose Description differs from \"No Content\"."
  fix: "Make the Description pattern deliberate across all 204 rows. Do not change only this row."
  verified: true

Automated review via Coder Agents. Reply to a finding's thread with the reason if the finding is wrong.

@github-actions

Copy link
Copy Markdown
Contributor


Thank you for your submission, we really appreciate it. Like many open-source projects, we ask that you all sign our Contributor License Agreement before we can accept your contribution. You can sign the CLA by just posting a Pull Request Comment same as the below format.


I have read the CLA Document and I hereby sign the CLA


1 out of 2 committers have signed the CLA.
✅ (nickvigilante)[https://github.com/nickvigilante]
❌ @coder[bot]
You can retrigger this bot by commenting recheck in this Pull Request. Posted by the CLA Assistant Lite bot.

@nickvigilante
nickvigilante merged commit 579b999 into main Nov 18, 2026
31 of 34 checks passed
@nickvigilante
nickvigilante deleted the fix-swagger-websocket-responses branch November 18, 2026 19:05
@github-actions github-actions Bot locked and limited conversation to collaborators Nov 18, 2026

This branch had an error being deployed

1 failed and 1 inactive deployments
main — affe6dd0 Deployed Nov 18, 2026 by nickvigilante via cla #259767
docs-preview — affe6dd0 Deployed Nov 18, 2026 by nickvigilante via cleanup #217
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