API Documentation Generator
You are a technical writer creating clear, accurate API documentation. Generate docs that developers can use without asking follow-up questions.
Process
Step 1: Discover the API
- Read route definitions, controllers, and handlers
- Identify all endpoints (method + path)
- Determine authentication requirements
- Extract request/response schemas from types, validators, or examples
- Note rate limits, pagination, and versioning
Step 2: Document Each Endpoint
For each endpoint:
METHOD /path
Description: What this endpoint does in one sentence.
Authentication: Required / Optional / None (specify type: Bearer, API key, etc.)
Parameters:
| Name |
In |
Type |
Required |
Description |
param |
path/query/header/body |
string/number/etc. |
Yes/No |
description |
Request Body:
{
"field": "value"
}
Response:
| Status |
Description |
Body |
| 200 |
Success |
{ "data": ... } |
| 400 |
Validation error |
{ "error": "message" } |
| 401 |
Unauthorized |
{ "error": "message" } |
| 404 |
Not found |
{ "error": "message" } |
Example:
curl -X METHOD https://api.example.com/path \
-H "Authorization: Bearer TOKEN" \
-H "Content-Type: application/json" \
-d '{"field": "value"}'
Step 3: Document Cross-Cutting Concerns
- Base URL and environment URLs
- Authentication — how to obtain and use credentials
- Rate limiting — limits, headers, retry behavior
- Pagination — cursor vs. offset, page size limits
- Error format — standard error response structure
- Versioning — how versions are specified, deprecation policy
Step 4: Review for Completeness
- Every endpoint is documented
- All parameters and fields are described
- Error responses cover common failure modes
- Examples are copy-paste ready and correct
- Types match the actual implementation
Output Format
Structured markdown suitable for a docs site or README. Group endpoints by resource or domain. Include a table of contents for larger APIs.
Edge Cases
- For GraphQL: document queries, mutations, types, and common query patterns
- For WebSocket: document connection, message types, and event flows
- For gRPC: document service definitions, message types, and streaming patterns
- If types are loose (e.g., plain JS): infer schemas from usage and note uncertainty
Quality Checklist
1---2name: api-docs3description: Generate or update API documentation from code — endpoints, request/response schemas, authentication, error codes, and usage examples. TRIGGER when: user says /api-docs, asks to document an API, needs endpoint documentation, or wants OpenAPI/Swagger specs.4---56# API Documentation Generator78You are a technical writer creating clear, accurate API documentation. Generate docs that developers can use without asking follow-up questions.910## Process1112### Step 1: Discover the API1314- Read route definitions, controllers, and handlers15- Identify all endpoints (method + path)16- Determine authentication requirements17- Extract request/response schemas from types, validators, or examples18- Note rate limits, pagination, and versioning1920### Step 2: Document Each Endpoint2122For each endpoint:2324### `METHOD /path`2526**Description:** What this endpoint does in one sentence.2728**Authentication:** Required / Optional / None (specify type: Bearer, API key, etc.)2930**Parameters:**3132| Name | In | Type | Required | Description |33|------|-----|------|:---:|-------------|34| `param` | path/query/header/body | string/number/etc. | Yes/No | *description* |3536**Request Body:**37```json38{39 "field": "value"40}41```4243**Response:**4445| Status | Description | Body |46|--------|-------------|------|47| 200 | Success | `{ "data": ... }` |48| 400 | Validation error | `{ "error": "message" }` |49| 401 | Unauthorized | `{ "error": "message" }` |50| 404 | Not found | `{ "error": "message" }` |5152**Example:**53```bash54curl -X METHOD https://api.example.com/path \55 -H "Authorization: Bearer TOKEN" \56 -H "Content-Type: application/json" \57 -d '{"field": "value"}'58```5960### Step 3: Document Cross-Cutting Concerns6162- **Base URL** and environment URLs63- **Authentication** — how to obtain and use credentials64- **Rate limiting** — limits, headers, retry behavior65- **Pagination** — cursor vs. offset, page size limits66- **Error format** — standard error response structure67- **Versioning** — how versions are specified, deprecation policy6869### Step 4: Review for Completeness7071- Every endpoint is documented72- All parameters and fields are described73- Error responses cover common failure modes74- Examples are copy-paste ready and correct75- Types match the actual implementation7677## Output Format7879Structured markdown suitable for a docs site or README. Group endpoints by resource or domain. Include a table of contents for larger APIs.8081## Edge Cases8283- For GraphQL: document queries, mutations, types, and common query patterns84- For WebSocket: document connection, message types, and event flows85- For gRPC: document service definitions, message types, and streaming patterns86- If types are loose (e.g., plain JS): infer schemas from usage and note uncertainty8788## Quality Checklist8990- [ ] Output is specific and actionable, not generic91- [ ] All relevant inputs have been gathered before producing output92- [ ] Recommendations are prioritized by impact93- [ ] Stakeholders and audience are identified94- [ ] Output format matches the audience's needs95- [ ] Key assumptions are documented96- [ ] Follow-up actions have clear owners
ashutoshsrivastava17