diegosouzapw API Documentation Generation Skill
Purpose: Generate and update API documentation from NestJS controllers. Keeps API docs in sync with implementation.
Trigger
When: Controller files (*.controller.ts) are modified
Context Needed: Controller code, DTOs, existing API docs
MCP Tools: grep_search, read_file, mcp_payment-syste_query_docs_by_type
Controller → Doc Mapping
Parse NestJS decorators to extract:
@Controller('products') // Base path: /api/v1/products
@Get(':id') // GET /api/v1/products/:id
@Post() // POST /api/v1/products
@UseGuards(JwtAuthGuard) // Auth required
@ApiOperation({ summary: '...'}) // Description
Extraction Rules
| Decorator | Extracted Info |
|---|---|
@Controller(path) |
Base path |
@Get/@Post/@Put/@Delete |
HTTP method |
@Param/@Query/@Body |
Parameters |
@UseGuards |
Authentication |
@ApiOperation |
Description |
@ApiResponse |
Response codes |
API Doc Format
### GET /api/v1/products/:id
**Description:** Get product by ID
**Authentication:** Required (JWT)
**Parameters:**
| Name | In | Type | Required | Description |
| :--- | :--- | :----- | :------- | :---------- |
| id | path | string | Yes | Product ID |
**Responses:**
| Code | Description | Schema |
| :--- | :---------- | :----------------- |
| 200 | Success | ProductResponseDto |
| 404 | Not found | ErrorDto |
**Example Request:**
```bash
curl -X GET /api/v1/products/abc123 \
-H "Authorization: Bearer {token}"
```
## Frontmatter Template
```yaml
---
document_type: "api-design"
module: "[module]"
status: "approved"
version: "1.0.0"
last_updated: "YYYY-MM-DD"
author: "@Backend"
keywords:
- "api"
- "rest"
- "[module]"
api_metadata:
base_path: "/api/v1/[resource]"
auth_required: true
rate_limited: true
---
Workflow
- Detect changes - Which controllers changed?
- Parse decorators - Extract API metadata
- Load DTOs - Get request/response types
- Find existing doc - Match by module
- Update endpoints - Add/modify/remove
- Bump version - If endpoints changed
- Update date - Set last_updated
DTO Extraction
// From DTO class
export class CreateProductDto {
@IsString()
@MinLength(1)
name: string;
@IsOptional()
@IsNumber()
price?: number;
}
// Generate table
| Field | Type | Required | Validation |
| name | string | Yes | MinLength(1) |
| price | number | No | - |