documenting-apis
Generate API specification documentation from codebase analysis. Detects REST endpoints, function signatures, type definitions, and schemas. Triggers: API specification, endpoints, REST API, type definitions, OpenAPI, Swagger, API documentation.
When & Why to Use This Skill
This Claude skill automates the generation of comprehensive API specification documentation by performing deep codebase analysis. It intelligently detects REST endpoints, function signatures, and data schemas across various frameworks like Express, FastAPI, and Next.js, ensuring your OpenAPI or Swagger documentation remains synchronized with your actual implementation.
Use Cases
- Legacy Project Documentation: Automatically generate a complete API specification for existing codebases that lack formal documentation, saving hours of manual reverse-engineering.
- Continuous Documentation Updates: Keep API docs in sync with rapid code changes by re-running the analysis to detect new endpoints or modified request/response schemas during the development cycle.
- Cross-Framework Analysis: Standardize documentation across polyglot microservices by extracting endpoint data from diverse environments including Node.js (Express/Next.js), Python (FastAPI/Flask), and Django.
- Type-Safe Schema Extraction: Extract detailed data models from TypeScript interfaces, Zod schemas, or Pydantic classes to provide developers with accurate request and response body definitions.
| name | documenting-apis |
|---|---|
| description | > |
| Triggers | API specification, endpoints, REST API, type definitions, |
| allowed-tools | Read, Write, Grep, Glob, Bash, Task |
docs:api - API Specification Generation
Auto-generate API documentation from codebase analysis.
Detection Items
| Category | Targets |
|---|---|
| REST Endpoints | Express, Fastify, Hono, Next.js, Flask, FastAPI, Django REST |
| Functions | tree-sitter extraction, TypeScript types, JSDoc, docstrings |
| Types | interface, type, Zod, Yup, dataclass, Pydantic |
| OpenAPI | openapi.yaml/json, swagger.yaml/json |
Framework Detection Patterns
| Framework | Pattern |
|---|---|
| Express/Fastify/Hono | app.get(), router.post() |
| Next.js | app/api/**/route.ts, pages/api/**/*.ts |
| Flask | @app.route() |
| FastAPI | @app.get(), @app.post() |
| Django REST | @api_view |
Analysis Scripts
| Script | Purpose |
|---|---|
scripts/detect-endpoints.sh |
HTTP method, path, handler, file location |
scripts/extract-types.sh |
Type name, fields, related types |
Generated Structure
# API Specification
## Endpoint List
### GET /api/users
**Request**: params table
**Response**: JSON example
## Type Definitions
### User
| Field | Type | Description |
Usage
/docs:api # Generate API docs
"Generate API specification" # Natural language
Markdown Validation
After generation, validate output with:
~/.claude/skills/scripts/validate-markdown.sh {output-file}
Non-blocking (warnings only) - style issues don't block document creation.
References
- Related:
documenting-architecture,setting-up-docs,documenting-domains