Api Documentation Generator

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