api-doc-generator

API Documentation Generator

Document APIs from authoritative artifacts and distinguish confirmed facts from inference.

Source priority

Use the strongest available source in this order:

1. Checked-in OpenAPI/Swagger contract and generated schema.
2. Framework route definitions and annotations.
3. Request/response models and validation rules.
4. Authentication, middleware, exception handling, and error catalogs.
5. Integration and contract tests.
6. 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

1. Detect the project framework, modules, existing API contracts, and documentation convention.
2. Determine the requested scope from the user's wording; infer the whole API only when no narrower scope exists.
3. Locate route registration, base paths, version prefixes, security middleware, models, validators, error handling, and tests.
4. 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:

1. Summary and evidence status
2. Method and full path
3. Authentication/authorization
4. Parameters and request body
5. Responses and supported errors
6. Minimal valid examples
7. 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.