api-doc-generator
Generate or update evidence-backed API documentation from OpenAPI specifications, framework routes, controllers, request/response models, validation rules, and tests. Use when the user explicitly asks for API or interface documentation, route inventory, endpoint reference, OpenAPI-derived docs, or synchronization between code and API docs. Supports OpenAPI-first projects and framework-specific discovery for Spring, FastAPI, NestJS, Express, and Gin; do not use for generic product documentation.
How do I install this agent skill?
npx skills add https://github.com/full-stack-skills/document-skills --skill api-doc-generatorIs this agent skill safe to install?
- Gen Agent Trust Hubpass
The 'api-doc-generator' skill is a comprehensive toolkit for generating API documentation from source code and OpenAPI specifications. It includes framework-specific discovery guides and a Python utility for inventory management. The skill incorporates security best practices by explicitly instructing the agent to redact sensitive data from generated examples and focuses entirely on local analysis without external network requirements.
- Socketpass
No alerts
- Snykpass
Risk: LOW · No issues
What does this agent skill do?
API Documentation Generator
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.
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/full-stack-skills/document-skills/api-doc-generator">View api-doc-generator on skillZs</a>