api-doc-generator

Q: How do I install api-doc-generator?

Run npx skills add https://github.com/full-stack-skills/document-skills --skill api-doc-generator in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/api-doc-generator/ (personal) or .claude/skills/api-doc-generator/ (project).

by full-stack-skillsBackend & APIs

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.

Installs: 87
Last 24h: —
Trending rank: —
Security: Not audited

Install

Works with every agent the skills CLI supports.

npx skills add https://github.com/full-stack-skills/document-skills --skill api-doc-generator

01
Install
Run the command in your project. The CLI asks which agents to install for.
02
Describe the task
Ask your agent for something this skill covers. It loads api-doc-generator automatically when relevant.
03
Review the result
The agent follows the SKILL.md steps, scripts and references bundled with the skill.

SKILL.md

The instructions your agent reads when the skill is triggered.

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.

FAQ

What does the api-doc-generator skill do?

How do I install api-doc-generator?

Run npx skills add https://github.com/full-stack-skills/document-skills --skill api-doc-generator in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/api-doc-generator/ (personal) or .claude/skills/api-doc-generator/ (project).

Which AI agents can use api-doc-generator?

Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.

Is api-doc-generator safe to install?

No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.

Who maintains api-doc-generator?

It is published by full-stack-skills in full-stack-skills/document-skills. It has 87 recorded installs.