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
1---2name: documenting-apis-23description: 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.4---5
6# docs:api - API Specification Generation
7
8Auto-generate API documentation from codebase analysis.
9
10## Detection Items
11
12| Category | Targets |
13| --- | --- |
14| REST Endpoints | Express, Fastify, Hono, Next.js, Flask, FastAPI, Django REST |
15| Functions | tree-sitter extraction, TypeScript types, JSDoc, docstrings |
16| Types | interface, type, Zod, Yup, dataclass, Pydantic |
17| OpenAPI | openapi.yaml/json, swagger.yaml/json |
18
19## Framework Detection Patterns
20
21| Framework | Pattern |
22| --- | --- |
23| Express/Fastify/Hono | `app.get()`, `router.post()` |
24| Next.js | `app/api/**/route.ts`, `pages/api/**/*.ts` |
25| Flask | `@app.route()` |
26| FastAPI | `@app.get()`, `@app.post()` |
27| Django REST | `@api_view` |
28
29## Analysis Scripts
30
31| Script | Purpose |
32| --- | --- |
33| `scripts/detect-endpoints.sh` | HTTP method, path, handler, file location |
34| `scripts/extract-types.sh` | Type name, fields, related types |
35
36## Generated Structure
37
38```markdown
39# API Specification
40
41## Endpoint List
42### GET /api/users
43**Request**: params table
44**Response**: JSON example
45
46## Type Definitions
47### User
48| Field | Type | Description |
49```
50
51## Usage
52
53```bash
54/docs:api # Generate API docs
55"Generate API specification" # Natural language
56```
57
58## Markdown Validation
59
60After generation, validate output with:
61
62```bash
63~/.claude/skills/scripts/validate-markdown.sh {output-file}
64```
65
66Non-blocking (warnings only) - style issues don't block document creation.
67
68## References
69
70- Related: `documenting-architecture`, `setting-up-docs`, `documenting-domains`
majiayu000