Repository navigation
fix: correct Swagger annotations that make the API reference inaccurate - #30121
Closed
nickvigilante wants to merge 1 commit into
Closed
nickvigilante wants to merge 1 commit into
nickvigilante wants to merge 1 commit into
Conversation
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
This was referenced Sep 29, 2026
Collaborator
Author
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to subscribe to this conversation on GitHub.
Already have an account?
Sign in.
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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.statuslisted onlyactiveandsuspended, notdormant, andTemplateVersion.warningslisted a value that does not exist).json.RawMessageand[]bytefields such as chat toolargsandresultwere documented as integer arrays.GET /api/v2/settings/idpsync/available-fieldsandfield-valuesdocumented a requiredorganizationpath parameter their URLs do not contain.200responses.statusenum values,format: uuidon array query parameters,exampleon header parameters (invalid in Swagger 2.0), and aWatchErrorCodevariant named_.Fix
enumstags 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.provisionerkeeps its tag because.swaggoreplacesProvisionerTypewithstring.swaggertype:"object"and[]bytefieldsswaggertype:"string" format:"byte", following the existingaudit.goandoauth2.gopattern.@Success 101, matching the other WebSocket routes, with a description of each message.chats/{chat}/streamandstream/partssend a JSON array batch per message, so they keep{array}.enums(...)and arrayformat(uuid), and name the zero valueWatchErrorUnspecified.204when there is no previous version.TemplateBuilderModuleVariable.defaultis now documented as an object, though the value can also be a scalar; a.swaggooverride to an untyped schema would be more accurate.The regenerated spec passes
swagger-cli validateschema checks, whichmainfails on the headerexample. It still reports the pre-existingPOST /api/v2/filesfile-parameter limitation already noted in that handler's description.Fixes DOCS-1122
🤖 Built with AI assistance.