---
name: api-documentation-generator
description: Generates OpenAPI/Swagger documentation from API route files. Use when working with REST APIs, Express routes, FastAPI endpoints, or when user requests API documentation.
allowed-tools: Read, Grep, Glob, Write, Edit
---

# API Documentation Generator

This skill automatically generates OpenAPI 3.0 (Swagger) documentation from API route files in your codebase.

## When to Use This Skill

- User asks to generate API documentation
- Working with REST API endpoints
- Need to create or update OpenAPI/Swagger specs
- Setting up API documentation for Express, FastAPI, Flask, NestJS, or similar frameworks

## Instructions

### 1. Discover API Routes

Search the codebase for API route definitions:

- **Express/Node.js**: Look for `app.get()`, `app.post()`, `router.get()`, etc.
- **FastAPI/Python**: Look for `@app.get()`, `@router.post()`, decorators
- **Flask**: Look for `@app.route()` decorators
- **NestJS**: Look for `@Get()`, `@Post()`, `@Controller()` decorators
- **Rails**: Look for routes in `config/routes.rb`

Use Glob to find route files (e.g., `**/*routes*.{js,ts,py}`, `**/controllers/**/*.{js,ts}`)

### 2. Analyze Route Patterns

For each discovered route, extract:

- **HTTP Method**: GET, POST, PUT, PATCH, DELETE
- **Path**: The endpoint URL (e.g., `/api/users/:id`)
- **Parameters**: Path params, query params, request body
- **Response**: Expected response structure
- **Authentication**: Whether auth is required
- **Description**: Comments or docstrings near the route

### 3. Generate OpenAPI Specification

Create or update an OpenAPI 3.0 specification file (typically `openapi.yaml` or `swagger.json`):

- Start with the template from `templates/openapi-3.0.yaml`
- Map each route to an OpenAPI path object
- Define request/response schemas using JSON Schema
- Include parameter definitions (path, query, body)
- Add authentication schemes if detected (Bearer, API Key, OAuth2)
- Group endpoints by tags (e.g., "Users", "Products", "Auth")

### 4. Validate Completeness

Check that the generated documentation includes:

- All discovered endpoints
- Accurate HTTP methods and paths
- Request/response examples where possible
- Error responses (400, 401, 404, 500, etc.)
- Security requirements

### 5. Output Location

- Save as `openapi.yaml` in the project root, or
- Place in `docs/` or `api/` directory if those exist
- Ask user for preferred location if unclear

## Framework-Specific Notes

### Express/Node.js
- Check for route middleware that might affect auth/validation
- Look for request validators (Joi, express-validator, etc.)
- Extract JSDoc comments for endpoint descriptions

### FastAPI
- FastAPI auto-generates OpenAPI docs, but this skill can enhance them
- Extract Pydantic models for request/response schemas
- Check for `response_model` and `status_code` parameters

### NestJS
- Look for DTOs (Data Transfer Objects) for schemas
- Check for Swagger decorators (`@ApiOperation`, `@ApiResponse`)
- Extract metadata from controller and method decorators

## Best Practices

1. **Use existing schemas**: If the codebase has TypeScript interfaces, Pydantic models, or similar, use them for accurate schemas
2. **Include examples**: Add request/response examples from tests if available
3. **Group logically**: Organize endpoints by resource or feature area using tags
4. **Version appropriately**: Use the API version from the codebase (e.g., "1.0.0")
5. **Add descriptions**: Use code comments/docstrings for endpoint descriptions

## Supporting Files

- `templates/openapi-3.0.yaml`: Base OpenAPI template
- `examples.md`: Framework-specific examples