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

1. Detect changes - Which controllers changed?
2. Parse decorators - Extract API metadata
3. Load DTOs - Get request/response types
4. Find existing doc - Match by module
5. Update endpoints - Add/modify/remove
6. Bump version - If endpoints changed
7. 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 | - |

Reference

• 04-API-DESIGN-TEMPLATE.md
• backend.instructions.md