Skip to content

fix: correct Swagger annotations that make the API reference inaccurate - #30121

Closed
nickvigilante wants to merge 1 commit into
mainfrom
fix-swagger-annotations
Closed

nickvigilante wants to merge 1 commit into
mainfrom
fix-swagger-annotations

Conversation

@nickvigilante

Copy link
Copy Markdown
Collaborator

Summary

The API reference under docs/reference/api/ is generated from Swagger comments and struct tags rather than from the Go types, and several of those annotations disagreed with what the server sends. This fixes four errors visible in the published reference and four spec defects that break validators and code generators. No handler behavior changes; the Go SDK and TypeScript types are unaffected.

Problem

  • enums:"..." tags narrowed named enum types, so the docs omitted valid values (for example, User.status listed only active and suspended, not dormant, and TemplateVersion.warnings listed a value that does not exist).
  • json.RawMessage and []byte fields such as chat tool args and result were documented as integer arrays.
  • GET /api/v2/settings/idpsync/available-fields and field-values documented a required organization path parameter their URLs do not contain.
  • Six WebSocket routes were documented as 200 responses.
  • The raw spec also had duplicated status enum values, format: uuid on array query parameters, example on header parameters (invalid in Swagger 2.0), and a WatchErrorCode variant named _.

Fix

  • Remove 34 enums tags that narrow or duplicate a named type, so the referenced type's full value list is used. Tags that describe an intentional subset stay: ACL role fields (which omit the "" deleted sentinel used only in update requests), APIKey.scope, and plain-string fields. Template.provisioner keeps its tag because .swaggo replaces ProvisionerType with string.
  • Tag raw JSON fields swaggertype:"object" and []byte fields swaggertype:"string" format:"byte", following the existing audit.go and oauth2.go pattern.
  • Mark the chat and watch WebSocket routes @Success 101, matching the other WebSocket routes, with a description of each message. chats/{chat}/stream and stream/parts send a JSON array batch per message, so they keep {array}.
  • Move header examples into descriptions, drop the redundant enums(...) and array format(uuid), and name the zero value WatchErrorUnspecified.
  • Document that the previous template version route returns 204 when there is no previous version.

TemplateBuilderModuleVariable.default is now documented as an object, though the value can also be a scalar; a .swaggo override to an untyped schema would be more accurate.

The regenerated spec passes swagger-cli validate schema checks, which main fails on the header example. It still reports the pre-existing POST /api/v2/files file-parameter limitation already noted in that handler's description.

Fixes DOCS-1122


🤖 Built with AI assistance.

The API reference is generated from Swagger comments and struct tags, and
several disagreed with what the server sends. Remove enums tags that
narrow a named enum type (User.status omitted dormant), document raw JSON
fields as objects and []byte fields as base64 strings, drop a nonexistent
path parameter from the deployment-level IdP sync routes, and mark chat
and watch WebSocket routes as 101 with a description of each message.

Also fix spec defects that break validators and code generators:
duplicated status enums, format(uuid) on array query parameters, example
on header parameters, and a WatchErrorCode enum variant named "_".

Assisted-by: AI
@linear-code

linear-code Bot commented Sep 29, 2026

Copy link
Copy Markdown

DOCS-1122

@nickvigilante

Copy link
Copy Markdown
Collaborator Author

Split into themed PRs: #30122 (enums), #30123 (JSON and byte field types), #30124 (parameters), and #30125 (WebSocket responses).

@github-actions github-actions Bot locked and limited conversation to collaborators Sep 29, 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