Document APIs from authoritative artifacts and distinguish confirmed facts from inference.
Source priority
Use the strongest available source in this order:
- Checked-in OpenAPI/Swagger contract and generated schema.
- Framework route definitions and annotations.
- Request/response models and validation rules.
- Authentication, middleware, exception handling, and error catalogs.
- Integration and contract tests.
- Runtime observations explicitly authorized by the user.
When sources disagree, report the mismatch instead of silently choosing one.
Framework routing
Read only the relevant reference:
- OpenAPI-first:
references/openapi-first.md - Java/Kotlin Spring:
references/spring.md - Python FastAPI:
references/fastapi.md - TypeScript NestJS:
references/nestjs.md - JavaScript/TypeScript Express:
references/express.md - Go Gin:
references/gin.md
Use references/scan-and-generate-example.md only when a complete worked example is useful.
For a checked-in OpenAPI document, generate a deterministic inventory before drafting prose:
python3 scripts/inventory_openapi.py path/to/openapi.yaml --output docs/api-inventory.md
The script refuses to overwrite an existing output unless --force is explicitly provided.
Workflow
1. Inspect
- Detect the project framework, modules, existing API contracts, and documentation convention.
- Determine the requested scope from the user's wording; infer the whole API only when no narrower scope exists.
- Locate route registration, base paths, version prefixes, security middleware, models, validators, error handling, and tests.
- Identify generated files so they are not mistaken for the source of truth.
2. Build an endpoint inventory
For each endpoint capture:
| Field | Requirement |
|---|---|
| Method and path | Resolve all prefixes and route groups |
| Operation identity | Handler/controller and stable operation name |
| Purpose | Derive from code/comments; mark inference |
| Authentication | Scheme, scopes/roles, and public exceptions |
| Request | Path/query/header/cookie/body fields and validation |
| Response | Status codes, content types, schema, and wrappers |
| Errors | Only errors supported by handlers, middleware, tests, or catalogs |
| Evidence | Contract or source location used |
Do not fabricate example values, undocumented error codes, required flags, or response fields.
3. Resolve schemas
- Follow nested model references and generic response wrappers.
- Preserve nullable, optional, enum, format, range, and length constraints.
- Detect pagination and list-envelope conventions.
- Show recursive or polymorphic schemas explicitly.
- Redact secrets and personal data from examples.
4. Generate the document
Use the repository's existing convention. If none exists, copy one template from assets/templates/ and write to a proposed path under docs/. Before writing, report the target and whether it already exists.
For every endpoint include:
- Summary and evidence status
- Method and full path
- Authentication/authorization
- Parameters and request body
- Responses and supported errors
- Minimal valid examples
- Source location
5. Validate
- Compare documented routes with the discovered inventory.
- Verify path variables and request fields against validators/models.
- Verify response and error status codes against code or contract.
- Check internal links and anchors.
- Mark unresolved conflicts and inferred fields.
- Never claim runtime verification unless the API was actually run.
Evidence labels
Use these labels when certainty matters:
已确认：契约— present in the checked-in API contract.已确认：源码— present in route/model/handler source.已确认：测试— exercised by a test.推断— reasonable but not explicitly specified.待确认— conflicting or missing evidence.
Completion contract
Report the generated/updated file, documented endpoint count, authoritative sources used, contract/source mismatches, inferred fields, and endpoints skipped because evidence was insufficient.