generate-api-docs

name	generate-api-docs
description	Generate API reference documentation from existing route definitions, controllers, and schemas. Produces a markdown API reference or OpenAPI YAML spec. Use when the API has no docs, outdated Swagger, or the team wants a readable markdown reference.

Generate API Documentation

Produce complete, accurate API documentation by reading route files, controllers, and schema definitions directly.

When to Use

• API has no documentation
• Swagger/OpenAPI spec is missing or outdated
• Team wants a human-readable markdown API reference
• Preparing docs to push to Confluence or a developer portal

Step 1: Locate API Definitions

Search for route/endpoint definitions in this priority order:

Express/Node.js:

• Router files: src/routes/, src/api/routes/, app/routes/
• Controller files: src/controllers/, src/api/controllers/
• Main app file where routes are registered

FastAPI/Python:

• Router files: app/routers/, src/api/
• main.py or app.py where routes are registered
• Pydantic models for request/response schemas

NestJS:

• *.controller.ts files
• *.module.ts for route grouping
• DTO files: *.dto.ts

Spring Boot:

• @RestController annotated classes
• @RequestMapping, @GetMapping, etc.
• Request/response DTO classes

Other:

• OpenAPI spec files: openapi.yaml, swagger.json, api-spec.yaml
• .proto files (gRPC)
• GraphQL schema files: schema.graphql, typeDefs.ts

Step 2: Extract Endpoint Information

For each endpoint, capture:

Method:    GET / POST / PUT / PATCH / DELETE
Path:      /api/v1/users/:id
Auth:      required (JWT) | optional | none
Summary:   Get user by ID
Handler:   UserController.getById (file:line)

Path params:
  id  UUID  User's unique identifier

Query params:
  include  string (optional)  Comma-separated relations to include (e.g., "posts,sessions")

Request body: (if applicable)
  {JSON schema or TypeScript interface}

Response 200:
  {shape found in controller return statement or serializer}

Response codes:
  200  Success
  400  Validation error
  401  Unauthenticated
  403  Unauthorized
  404  Not found
  500  Internal error

Step 3: Extract Auth Requirements

Document globally:

• What auth scheme is used (JWT, API Key, Session, OAuth2)
• How to obtain credentials (if visible in auth routes)
• Where to pass them (Authorization header, query param, cookie)
• Which endpoints are public vs protected

Step 4: Extract Common Error Formats

Find the error response shape (look at error middleware or existing 4xx/5xx responses):

{
  "message": "string",
  "code": "string",
  "details": {}
}

Step 5: Output Format Choice

Ask: "Which format do you need?"

• A — Markdown API reference (human-readable, good for Confluence/GitHub)
• B — OpenAPI 3.0 YAML (machine-readable, Swagger UI compatible)
• C — Both

---

Output A: API_REFERENCE.md

Write to: {project-root}/docs/API_REFERENCE.md

# API Reference — {project_name}

> Generated by Scout on {date}. Source: route files in `{src/api/}`.

## Base URL

`{/api/v1}` (configure via {BASE_URL} env var)

## Authentication

**Type:** {JWT Bearer Token}

Include token in all authenticated requests:

Authorization: Bearer <your_token>

Obtain token via: `POST /auth/login`

---

## Resources

### Users

#### GET /users
List users.

**Auth:** Required  
**Query params:**
| Param | Type | Default | Description |
|-------|------|---------|-------------|
| page | number | 1 | Page number |
| limit | number | 20 | Results per page |

**Response 200:**
```json
{
  "data": [{ "id": "uuid", "email": "string", "name": "string" }],
  "total": 100,
  "page": 1
}

---

POST /users

Create a user.

{... and so on per endpoint ...}

---

Error Responses

All errors follow this format:

{
  "message": "Human-readable error",
  "code": "MACHINE_READABLE_CODE"
}

HTTP Code	Meaning
400	Validation error — check details field
401	Missing or invalid token
403	Insufficient permissions
404	Resource not found
500	Internal server error

---

## Output B: openapi.yaml

Write to: `{project-root}/docs/openapi.yaml`

```yaml
openapi: "3.0.3"
info:
  title: {project_name} API
  version: "{version from package.json or 1.0.0}"
  description: "{description}"
servers:
  - url: http://localhost:{PORT}/api/v1
    description: Local development

components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
  schemas:
    {User}:
      type: object
      properties:
        id:
          type: string
          format: uuid
        email:
          type: string
          format: email
      required: [id, email]
    Error:
      type: object
      properties:
        message: { type: string }
        code: { type: string }

paths:
  /users:
    get:
      summary: List users
      security:
        - BearerAuth: []
      parameters:
        - name: page
          in: query
          schema: { type: integer, default: 1 }
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/User'

Handling Undocumented Behaviors

If a handler doesn't have clear response typing:

• Trace through the controller to the service return value
• Note: > Response shape inferred from service return type — verify before publishing

TODOs

Mark any endpoint that couldn't be fully documented:

<!-- TODO: Response shape for GET /users/:id/posts not determinable — 
     UserController.getPosts has implicit any return type -->

List all TODOs at the end so user knows what needs manual review.