fix(swagger): align api-tools proxy schemas with actual responses#52
Open
torrid-fish wants to merge 4 commits into
Open
fix(swagger): align api-tools proxy schemas with actual responses#52torrid-fish wants to merge 4 commits into
torrid-fish wants to merge 4 commits into
Conversation
- /v1/mark-accent/stream: replace `@Success 200 {string} string` with a
proper `MarkAccentStreamChunk` schema so Swagger UI shows the real
NDJSON line shape instead of a literal "string". Closes #50.
- Add `ProxyErrorResponse` for the 502 body the reverse proxy writes
(`{"error": "Failed to contact external API"}`). Was `map[string]string`,
which Swagger UI rendered as a generic `additionalProp*: string` map.
- Tidy `APIToolsError` embedded examples so a successful response's
`error` field renders as `{code:0, message:" "}` instead of the
alarming literal `{code:500, message:"HTTP error 500"}` that swag was
compositing into otherwise-200 examples.
- `swaggerignore` the recursive `WordAccentSubword.Subword` field — swag
renders self-referential types as `["string"]`; the field is "reserved
for compatibility; typically empty" in real responses anyway.
- Append a `Body convention:` sentence to every api-tools handler's
`@Description` explaining that the body's `status` field carries the
real result code and `error` is `null` on success. swag drops
`description:` siblings of `$ref`, so the field-level convention had
nowhere else to land.
Closes #50
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
This comment was marked as resolved.
This comment was marked as resolved.
Sorry, something went wrong.
Per-endpoint exceptions are delivered inside the body as `{status: 5xx,
result: null, error: {...}}` (api-tools follows JSON-RPC 2.0 over HTTP).
The previous schema declared `result` as a non-null array/object, so
OpenAPI codegen producing strict client types (TypeScript, Java, Kotlin)
would reject or NPE on valid failed responses instead of surfacing the
embedded `error`.
Tag every `result` field with `extensions:"x-nullable=true"`. For pointer
fields (`*IdDetails`, `*SentenceQueryWordResult`) swag emits an `allOf`
wrapper so the `x-nullable` extension can sit alongside the `$ref`. Also
covers the streaming endpoint flagged by codex on PR #52 — same body
convention applies to every chunk.
Refs #52 (comment)
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 join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
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.
目的
Swagger UI 上
/v1/mark-accent/stream的 Example Value 只顯示一個字面"string"，跟實際 NDJSON 完全對不起來（#50）。順手把其他 api-tools proxy 路由幾個會誤導使用者的 schema 雷一起修掉。方法／實作說明
主要修改：
internal/api/api_tools.go：handler annotations（@Success/@Failure/@Description）internal/api/api_tools_models.go：新增MarkAccentStreamChunk/ProxyErrorResponse，調整APIToolsError與WordAccentSubword，清理 dead description tagsdocs/swagger/{docs.go,swagger.json,swagger.yaml}：make swag重新產生關鍵實作：
@Success 200 {string} string→{object} MarkAccentStreamChunk，包含{chunk, subchunk, status, result, error}五個 top-level 欄位（對照實際 payload 確認）。ProxyErrorResponse { error string }，與proxyTo的ErrorHandler實際輸出{"error": "Failed to contact external API"}對齊；7 個 handler 的@Failure 502全部換掉。code:500 / message:"HTTP error 500"，在 200 success response 的合成 example 裡造成status:200卻error.code:500的矛盾畫面。改成code:0 / message:" "（swag 不接受空字串，會 fallback 成字面"string"，所以用單空白）。WordAccentSubword.Subword（自我引用[]WordAccentSubword）標swaggerignore:"true"，因為 swag 把 self-referential type 渲染成["string"]；該欄位 description 本就是「reserved for compatibility; typically empty」，runtime JSON 仍然輸出。error欄位的 variant 註記：每個 handler 的@Description末尾追加Body convention: the inner status carries the real result code; error is null on success and populated only when status != 200.（swag 在 OpenAPI 2.0 模式下會丟棄\$ref欄位上的 siblingdescription，所以欄位標籤上寫不下，搬到 endpoint description 才看得到）。關聯 Issue
Closes #50
附註
feat/api-tools）——api_tools_models.go與 stream endpoint 都來自 7db676f，main 還沒有。一旦 feat(deploy): self-host stack, api-tools integration, auth hardening #38 合進 main，這個 PR 的 base 會自動跟著移過去。/v1/mark-accent/stream的 Example Value 已是 chunk shape，502 example 顯示{"error": "..."}🤖 Generated with Claude Code