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.