API Documentation Generator

Generate production-ready OpenAPI 3.1 specifications and documentation from your codebase.

Workflow

Phase 1: Discovery

1. Detect framework by scanning for:

• package.json → Express, NestJS, Fastify, Hono
• requirements.txt / pyproject.toml → FastAPI, Flask, Django REST
• go.mod → Gin, Echo, Chi, Fiber
• Gemfile → Rails API
• pom.xml / build.gradle → Spring Boot
• Cargo.toml → Axum, Actix-web

1. Find API entry points:

   # Common patterns to search
   app.get|post|put|patch|delete  # Express/Fastify
   @app.route|@router             # Flask/FastAPI
   @GetMapping|@PostMapping       # Spring
   router.GET|POST                # Gin/Echo
   resources|get|post             # Rails
   @Controller|@Get|@Post         # NestJS

1. Extract endpoint metadata:

• HTTP method and path
• Path parameters (:id, {id}, <id>)
• Query parameters
• Request body schema
• Response schemas and status codes
• Authentication requirements
• Middleware/decorators

Phase 2: Schema Extraction

1. Type definitions → OpenAPI components/schemas:

• TypeScript interfaces/types
• Python Pydantic models, dataclasses, TypedDict
• Go structs with json tags
• Java/Kotlin DTOs
• Ruby serializers

1. Validation rules → OpenAPI constraints:

• Required fields
• Min/max values
• String patterns (email, uuid, etc.)
• Enums
• Array constraints

1. Existing documentation:

• JSDoc/TSDoc comments
• Python docstrings
• Go doc comments
• Swagger/OpenAPI annotations
• README files

Phase 3: OpenAPI Generation

Generate openapi.yaml with:

openapi: 3.1.0
info:
  title: <extracted from package.json/pyproject.toml or ask>
  version: <from version file or git tag>
  description: <from README or generate>
servers:
  - url: <detect from env/config or use placeholder>
paths:
  /endpoint:
    get:
      summary: <from docstring or generate>
      description: <detailed description>
      operationId: <function name>
      tags: [<from route grouping>]
      parameters: [<extracted>]
      requestBody: <if applicable>
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseType'
              example: <generate realistic example>
        '400': <validation errors>
        '401': <if auth required>
        '404': <if path params>
        '500': <server error>
      security: [<detected auth>]
components:
  schemas: <all extracted types>
  securitySchemes: <detected auth methods>

Phase 4: Documentation Output

Based on $ARGUMENTS or default to all:

1. OpenAPI Spec (openapi.yaml):

• Valid OpenAPI 3.1
• Realistic examples for all schemas
• Comprehensive error responses

1. Markdown (API.md):

• Table of contents
• Authentication section
• Endpoint reference with examples
• Schema definitions
• Error codes

1. Postman Collection (postman.json):

• Importable collection
• Environment variables
• Pre-configured requests

Phase 5: Validation

Before finalizing, validate:

1. Spec validity:

   npx @redocly/cli lint openapi.yaml

Or if not available, validate structure manually.

1. Coverage check: List any endpoints found but not documented

1. Quality checks:

• All endpoints have descriptions
• All parameters documented
• Response examples provided
• Auth requirements specified

Framework-Specific Patterns

See reference.md for detailed extraction patterns per framework.

Output Format Selection

Example Usage

/api-docs                    # Auto-detect, generate all formats
/api-docs fastapi openapi    # FastAPI project, OpenAPI only
/api-docs express markdown   # Express project, Markdown only

Quality Standards

Generated documentation MUST include:

• [ ] All public endpoints documented
• [ ] Request/response examples for each endpoint
• [ ] Authentication requirements clearly stated
• [ ] Error responses documented (4xx, 5xx)
• [ ] Parameter constraints (required, types, validation)
• [ ] Consistent naming and formatting