review/skills/api-doc/SKILL.md

---

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.