From dfaa66fedac5149bf610af820d0733cc2b9bc2d8 Mon Sep 17 00:00:00 2001 From: Jeffery Date: Thu, 27 Aug 2026 15:41:38 +0800 Subject: [PATCH] =?UTF-8?q?feat(api-doc):=20=E6=96=B0=E5=A2=9E=20API=20?= =?UTF-8?q?=E6=96=87=E4=BB=B6=E7=A8=BD=E6=A0=B8=E6=8A=80=E8=83=BD?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit What：新增 skills/api-doc/SKILL.md。六步流程：偵測 Swagger 支援、不支援就回報 並停手、列出稽核範圍、分三個面向各開一個 sub agent 稽核、彙整去重排序、回報 發現。三個面向分別是狀態碼的回覆類型、參數說明與範例、資料模型遞迴。本技能 只回報「檔案:行號」、嚴重度與建議修法，不改程式碼。 Why：支援 Swagger 的專案要把控制器文件補全：所有可能出現的狀態碼都宣告回覆 類型，輸入輸出都要有說明與真實資料範例，參數是資料模型就每個屬性都套用、內含 模型再往下遞迴。這是 code-review 六組沒碰過的領域，跟第 5 組的原始碼註解契約 也不是同一件事，所以獨立成一支技能，不塞進既有的六組裡。 How：第一步跑 tools/swagger-detect.sh，讀結束碼決定走下去還是停手，不支援時 一個 sub agent 都不開，直接回報未啟用。範例優先取專案的真實資料，資料庫、 種子資料、測試夾具都算；真的取不到才依邏輯推導，並在文件裡標上「推導值」， 讓後面讀的人知道這個值沒被觀察過。取自資料庫的範例一律去識別化，個人資料不 進 Swagger 文件。分工另立一節：本技能只管 Swagger 文件屬性，原始碼註解契約 歸 code-review 第 5 組，同一個缺失不會被回報兩次。 Who：jsc-review 新增的 api-doc 技能，由 jsc-sdlc 的 implement 收尾時呼叫。 --- skills/api-doc/SKILL.md | 58 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 58 insertions(+) create mode 100644 skills/api-doc/SKILL.md diff --git a/skills/api-doc/SKILL.md b/skills/api-doc/SKILL.md new file mode 100644 index 0000000..d2135ed --- /dev/null +++ b/skills/api-doc/SKILL.md @@ -0,0 +1,58 @@ +--- +name: api-doc +description: Audit an API project's Swagger/OpenAPI documentation: every returnable HTTP status code declares a response type, and every input and output carries a description plus a real data example, recursively down nested data models. Run after controller work or an implementation is complete, e.g. from jsc-sdlc implement, next to jsc-review:code-review. Detection runs first via tools/swagger-detect.sh; without both the Swagger package and its wiring, report unsupported and stop. The source comment contract belongs to jsc-review:code-review group 5; this skill covers Swagger document attributes only. Findings carry file:line, severity, and the fix; this skill never modifies code. +--- + +# api-doc + +Audit whether an API project's Swagger (OpenAPI) documentation is complete enough for a caller to integrate against it without reading the implementation. + +## When to run + +1. **After controller work is complete**: one controller or one related group of controllers is done. +2. **When an implementation is complete**: all todos of a work package that touched API endpoints are done. This is the call site in `jsc-sdlc:implement`, right next to `jsc-review:code-review`. +3. **Never on a project without Swagger**: step 1 below decides this in code, not by judgment. + +## Division of labor + +- This skill covers **Swagger document attributes only**: response type declarations, Swagger parameter descriptions, and Swagger examples. +- The comment contract — method description, layer tag, parameter description, return description, examples, nested-structure comments — belongs to `jsc-review:code-review` group 5 (`references/smells.md` 5.1 to 5.8). Never report the same gap twice; when a nested model already fails 5.5, leave it to `code-review`. +- Security, logic bugs, and test coverage belong to the CLI's built-in review. + +## Steps + +1. Detect Swagger support: run `tools/swagger-detect.sh {project path}` (defaults to the current directory). The script confirms package **and** wiring, so an installed-but-never-enabled project comes back unsupported. Read its exit code: `0` supported, `1` unsupported, `2` bad argument or missing path. Completion condition: the exit code and the `support=`, `stack=`, `package=`, `config=` lines are captured. +2. On exit code `1`, report the literal 「本專案未啟用 Swagger 文件，略過 API 文件稽核」 plus the `stack=` and `package=` lines the script printed, and stop. Spawn no sub agent. On exit code `2`, report the script's error message verbatim and stop; the caller supplies a valid project path and re-runs. Completion condition: the run has ended with an honest reason, or exit code `0` moved it to step 3. +3. List the audit scope: every controller in the project, or only the controllers touched by `git diff` when the caller asked for a scoped run. Completion condition: the controller list is non-empty and reported; an empty list ends the run with the literal 「無發現」. +4. Audit in three aspects, and every aspect **MUST run as a sub agent**; the three may run in parallel: + + | Aspect | Scope | + | --- | --- | + | 1 Status codes | For every action, every HTTP status code it can actually return — success, validation failure, authorization failure, not found, server error — has a declared response type and body schema (`ProducesResponseType`, `@ApiResponse`, FastAPI `responses=`, drf-spectacular `@extend_schema`). A status code the code can produce but the document never declares is a finding; so is a declared status code the code can never produce | + | 2 Parameter description and example | Every input parameter and every output field has a description and an example. Examples come from real project data first — query the project's database, seed data, or fixtures. Only when real data is unreachable, derive an example by logic and mark it as a derived value in the document itself | + | 3 Recursive data model | When a parameter or return value is a data model, aspect 2 applies to every one of its properties. A model containing another model recurses to the innermost layer. Walk in from the controller and follow the input and output types down | + + Instructions for each sub agent: read only, change nothing; report each finding as `file:line`, the aspect, severity, one sentence of evidence, and the concrete fix (which attribute to add, on which member). Findings are reported in Traditional Chinese. + + Completion condition: all three aspects have returned — an aspect with nothing to report still returns 「無發現」 for itself. +5. Merge the three aspects' findings: deduplicate by location, then sort by severity. Start this step only once all three have returned. Completion condition: every finding appears exactly once, ordered 高 → 中 → 低. +6. Report the finding list. **This skill never modifies code**; the caller decides what to fix. Completion condition: the report is handed to the caller and the fix decision is left to them. + +## Severity + +The 高、中、低 scale is the one in `references/smells.md`. Map this skill's findings onto it: + +| Finding | Severity | +| --- | --- | +| A returnable status code has no declared response type | 高 | +| A declared response type does not match the body the code returns | 高 | +| An input or output has no description | 中 | +| A data model property is missing from the recursive walk entirely | 中 | +| A placeholder example while real data was reachable | 低 | +| A derived example that is not marked as derived | 低 | + +## Notes + +- Examples taken from a database must be de-identified. Never put personal data into a Swagger document. +- 「推導值」 is the literal marker for a derived example; keep it in the document text so the next reader knows the value was never observed. +- When there are no findings, report the literal 「無發現」 explicitly; never leave the report empty.