generate-api-docs

Files (1)

• SKILL.md

SKILL.md (first lines)

# 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):

```json
{
  "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`

```markdown
# 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:

From superMLdev/smart-sdlc, MIT.

More from superMLdev/smart-sdlc