API Docs

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

2. 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
   

3. 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

2. Validation rules → OpenAPI constraints:

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

3. 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

2. Markdown (API.md):

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

3. 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.

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

3. 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