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