api-docs

API Documentation Generator

You are tasked with generating professional, comprehensive API documentation from code. Support multiple API styles (REST, GraphQL, gRPC) and output in standard formats (OpenAPI/Swagger, GraphQL Schema, etc.).

Step 1: Identify API Type and Structure

Scan the codebase to determine:

REST APIs:

• Express.js routes (app.get, app.post, router.use)
• FastAPI endpoints (@app.get, @app.post)
• Spring Boot controllers (@RestController, @GetMapping)
• Flask routes (@app.route)
• Django views and URLs
• ASP.NET Core controllers ([HttpGet], [HttpPost])

GraphQL APIs:

• Schema definitions (.graphql files)
• Resolver implementations
• Type definitions (TypeDefs)
• Mutations and Queries

gRPC APIs:

• Protocol buffer definitions (.proto files)
• Service definitions
• Message types

Generic APIs:

• HTTP handlers
• RPC endpoints
• WebSocket handlers

Step 2: Extract API Endpoint Information

For each endpoint, gather:

Endpoint Metadata:

• HTTP Method: GET, POST, PUT, DELETE, PATCH, etc.
• Path: /api/v1/users/{id}
• Path Parameters: {id}, {userId}, etc.
• Query Parameters: ?page=1&limit=10
• Request Headers: Authorization, Content-Type, etc.
• Request Body: Schema and examples
• Response Codes: 200, 201, 400, 401, 404, 500, etc.
• Response Body: Schema for each response code
• Authentication: Required? Type? (Bearer, OAuth2, API Key)
• Rate Limiting: Limits and headers
• Deprecation: Is it deprecated?

Code Analysis:

• Read route handler implementations
• Extract validation logic (required fields, types, constraints)
• Identify error handling patterns
• Find authentication/authorization middleware
• Detect request/response transformations
• Locate example responses in code or tests

Step 3: Generate OpenAPI 3.0 Specification

Create a complete OpenAPI document:

openapi: 3.0.3
info:
  title: [Project Name] API
  description: |
    [Multi-line description of the API]

    ## Authentication
    [Describe authentication methods]

    ## Rate Limiting
    [Describe rate limiting policies]

    ## Versioning
    [Describe versioning strategy]
  version: 1.0.0
  contact:
    name: [Team Name]
    email: [[email protected]]
    url: [https://example.com]
  license:
    name: [License Type]
    url: [License URL]

servers:
  - url: https://api.example.com/v1
    description: Production server
  - url: https://staging-api.example.com/v1
    description: Staging server
  - url: http://localhost:3000/v1
    description: Development server

tags:
  - name: Users
    description: User management operations
  - name: Orders
    description: Order processing and management
  - name: Products
    description: Product catalog operations

paths:
  /users:
    get:
      tags:
        - Users
      summary: List all users
      description: |
        Retrieves a paginated list of users. Supports filtering,
        sorting, and searching.
      operationId: listUsers
      parameters:
        - name: page
          in: query
          description: Page number for pagination
          required: false
          schema:
            type: integer
            minimum: 1
            default: 1
        - name: limit
          in: query
          description: Number of items per page
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 20
        - name: search
          in: query
          description: Search term for filtering users
          required: false
          schema:
            type: string
        - name: sort
          in: query
          description: Sort field and order (e.g., "name:asc", "created_at:desc")
          required: false
          schema:
            type: string
            enum: [name:asc, name:desc, created_at:asc, created_at:desc]
      responses:
        '200':
          description: Successful response with user list
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/User'
                  pagination:
                    $ref: '#/components/schemas/Pagination'
              examples:
                success:
                  summary: Example successful response
                  value:
                    data:
                      - id: "usr_123456"
                        email: "[email protected]"
                        name: "John Doe"
                        created_at: "2024-01-15T10:30:00Z"
                      - id: "usr_789012"
                        email: "[email protected]"
                        name: "Jane Smith"
                        created_at: "2024-01-16T14:20:00Z"
                    pagination:
                      page: 1
                      limit: 20
                      total: 150
                      total_pages: 8
        '400':
          description: Invalid request parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                invalid_page:
                  summary: Invalid page parameter
                  value:
                    error:
                      code: "INVALID_PARAMETER"
                      message: "Page must be a positive integer"
                      field: "page"
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
      security:
        - bearerAuth: []

    post:
      tags:
        - Users
      summary: Create a new user
      description: Creates a new user account with the provided information
      operationId: createUser
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserCreate'
            examples:
              basic:
                summary: Basic user creation
                value:
                  email: "[email protected]"
                  name: "New User"
                  password: "securePassword123!"
      responses:
        '201':
          description: User created successfully
          headers:
            Location:
              description: URL of the created user
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '400':
          description: Invalid user data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: User already exists
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
        - bearerAuth: []

  /users/{userId}:
    get:
      tags:
        - Users
      summary: Get user by ID
      description: Retrieves detailed information about a specific user
      operationId: getUserById
      parameters:
        - name: userId
          in: path
          description: Unique identifier of the user
          required: true
          schema:
            type: string
            pattern: '^usr_[a-zA-Z0-9]+$'
          example: "usr_123456"
      responses:
        '200':
          description: User found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '404':
          $ref: '#/components/responses/NotFound'
      security:
        - bearerAuth: []

    put:
      tags:
        - Users
      summary: Update user
      description: Updates all fields of an existing user (full update)
      operationId: updateUser
      parameters:
        - name: userId
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserUpdate'
      responses:
        '200':
          description: User updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '404':
          $ref: '#/components/responses/NotFound'
      security:
        - bearerAuth: []

    delete:
      tags:
        - Users
      summary: Delete user
      description: Permanently deletes a user account
      operationId: deleteUser
      parameters:
        - name: userId
          in: path
          required: true
          schema:
            type: string
      responses:
        '204':
          description: User deleted successfully
        '404':
          $ref: '#/components/responses/NotFound'
      security:
        - bearerAuth: []

components:
  schemas:
    User:
      type: object
      required:
        - id
        - email
        - name
      properties:
        id:
          type: string
          description: Unique identifier for the user
          example: "usr_123456"
        email:
          type: string
          format: email
          description: User's email address
          example: "[email protected]"
        name:
          type: string
          description: User's full name
          minLength: 1
          maxLength: 100
          example: "John Doe"
        avatar_url:
          type: string
          format: uri
          description: URL to user's avatar image
          nullable: true
          example: "https://cdn.example.com/avatars/user123.jpg"
        role:
          type: string
          enum: [user, admin, moderator]
          description: User's role in the system
          default: user
        is_active:
          type: boolean
          description: Whether the user account is active
          default: true
        created_at:
          type: string
          format: date-time
          description: Timestamp when the user was created
          example: "2024-01-15T10:30:00Z"
        updated_at:
          type: string
          format: date-time
          description: Timestamp when the user was last updated
          example: "2024-01-20T15:45:00Z"

    UserCreate:
      type: object
      required:
        - email
        - name
        - password
      properties:
        email:
          type: string
          format: email
          description: User's email address (must be unique)
        name:
          type: string
          minLength: 1
          maxLength: 100
          description: User's full name
        password:
          type: string
          format: password
          minLength: 8
          description: User's password (min 8 characters)
        role:
          type: string
          enum: [user, admin]
          default: user

    UserUpdate:
      type: object
      properties:
        email:
          type: string
          format: email
        name:
          type: string
          minLength: 1
          maxLength: 100
        avatar_url:
          type: string
          format: uri
          nullable: true
        is_active:
          type: boolean

    Pagination:
      type: object
      properties:
        page:
          type: integer
          description: Current page number
        limit:
          type: integer
          description: Items per page
        total:
          type: integer
          description: Total number of items
        total_pages:
          type: integer
          description: Total number of pages

    Error:
      type: object
      required:
        - error
      properties:
        error:
          type: object
          required:
            - code
            - message
          properties:
            code:
              type: string
              description: Machine-readable error code
              example: "INVALID_PARAMETER"
            message:
              type: string
              description: Human-readable error message
              example: "The provided email is invalid"
            field:
              type: string
              description: Field that caused the error (if applicable)
              example: "email"
            details:
              type: object
              description: Additional error details
              additionalProperties: true

  responses:
    Unauthorized:
      description: Authentication required or invalid token
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: "UNAUTHORIZED"
              message: "Valid authentication token required"

    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: "NOT_FOUND"
              message: "The requested resource was not found"

    RateLimitExceeded:
      description: Too many requests
      headers:
        X-RateLimit-Limit:
          description: Request limit per time window
          schema:
            type: integer
        X-RateLimit-Remaining:
          description: Remaining requests in current window
          schema:
            type: integer
        X-RateLimit-Reset:
          description: Time when the rate limit resets (Unix timestamp)
          schema:
            type: integer
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: "RATE_LIMIT_EXCEEDED"
              message: "Too many requests. Please try again later."

  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: |
        JWT token obtained from the /auth/login endpoint.
        Include in the Authorization header as: `Bearer <token>`

    apiKey:
      type: apiKey
      in: header
      name: X-API-Key
      description: API key for service-to-service communication

    oauth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://auth.example.com/oauth/authorize
          tokenUrl: https://auth.example.com/oauth/token
          scopes:
            read:users: Read user information
            write:users: Modify user information
            admin: Full administrative access