api-docs-generator

API Documentation Generator

Generate clean, structured Markdown API reference docs from source code, OpenAPI/Swagger specs, or route definitions.

Gather Context

Before writing anything, determine:

1. Source — Controller, route file, OpenAPI spec (JSON/YAML), or a set of files?
2. API name — e.g., "User Management API". Infer from class/file name if not stated.
3. Base URL — e.g., https://api.example.com/v1. Default to https://api.example.com if unknown.
4. Auth method — Bearer token (default), API key, OAuth 2.0, or none.
5. Output format:
   • single-file (default) — one Markdown file with all endpoints
   • per-endpoint — one file per endpoint ({method}-{path-slug}.md) plus a README.md index
6. Language/framework — Auto-detect from file extensions, imports, and decorators.

If context is missing: In conversational mode, ask. In agent/inline mode, use sensible defaults and note your assumptions at the top of the output.

Analyzing the Source

From Source Code

Read the file(s) and extract:

• Every endpoint: HTTP method + route path
• Route params, query params, request body schemas
• Response types, status codes, and return models
• Auth requirements (per-endpoint if they vary)
• Doc comments, decorators, or annotations (/// <summary>, @ApiOperation, @app.get(...), JSDoc @param/@returns, etc.)

Framework detection hints:

From OpenAPI/Swagger Specs

Parse the spec and map directly:

• paths → endpoints
• parameters → params table
• requestBody → request body section
• responses → response table + examples
• components/schemas → inline the referenced models
• securityDefinitions / securitySchemes → auth section
• info.title, info.version, servers[0].url → header metadata

Prefer descriptions from the spec. Only infer descriptions when the spec omits them.

Handling Incomplete Source

If the source references models, DTOs, or types defined in other files:

• Document what's visible. Use the type name as-is (e.g., UserDto) and note that the full schema is defined elsewhere.
• If the user provides multiple files, cross-reference them to build complete schemas.
• Never fabricate fields for a model you can't see.

Documentation Template

# {API Name} — API Reference

> Base URL: `{base-url}`
> Authentication: {auth-method}
> Version: {version}

## Table of Contents

- [Authentication](#authentication)
- [{Resource Group}](#{resource-group-slug})
  - [{METHOD} {path}](#{endpoint-anchor})

## Authentication

{How to authenticate: header format, token acquisition, expiration/refresh if known.}

**Header format:**

```
Authorization: Bearer {token}
```

---

## {Resource Group}

### {METHOD} `{path}`

{One-line description from doc comments or inferred from the code.}

**Parameters**

| Name | In | Type | Required | Description |
|------|----|------|----------|-------------|
| `id` | path | integer | ✅ | Resource ID |
| `limit` | query | integer | ❌ | Max results (default: 20) |

**Request Body** *(POST/PUT/PATCH only)*

```json
{
  "email": "string — the user's email address",
  "displayName": "string — display name"
}
```

**Responses**

| Status | Description |
|--------|-------------|
| `200 OK` | Returns the resource |
| `404 Not Found` | Resource not found |

```json
{
  "id": 42,
  "email": "jane@example.com",
  "displayName": "Jane Smith",
  "createdAt": "2026-01-15T10:30:00Z"
}
```

**Example**

```bash
curl -X GET "{base-url}/{path}" \
  -H "Authorization: Bearer eyJhbG..."
```

For per-endpoint format: one file per endpoint named {method}-{path-slug}.md (e.g., get-users-id.md), each using the endpoint section above, plus a README.md that links to all of them grouped by resource.

Common API Patterns to Document

When you encounter these in the source, document them:

• Pagination — query params like page, limit, offset, cursor. Note defaults and max values if visible.
• Filtering/sorting — query params like sort, filter, q, status. Document allowed values.
• Rate limiting — if headers like X-RateLimit-* or decorators like @Throttle() are present, add a "Rate Limiting" section.
• Versioning — if the API uses path versioning (/v1/, /v2/) or header versioning, note it in the header.
• Bulk operations — endpoints accepting arrays or batch payloads.

Rules

Do:

• Extract only what exists in the source — never invent endpoints, params, or fields
• Use exact route paths, param names, and types from the code
• Preserve existing descriptions from doc comments, annotations, or spec descriptions
• Include a curl example for every endpoint
• Use realistic fake data in examples (jane@example.com, 42, "acme-corp" — not "string" or "value")
• Document both success and error responses
• Use standard HTTP status descriptions (200 OK, 201 Created, 400 Bad Request, 401 Unauthorized, 404 Not Found, etc.)
• Flag ambiguity with a note (e.g., "Response schema inferred from return type; actual response may differ")

Don't:

• Invent endpoints or params that aren't in the source
• Use placeholder junk like "string", "value", or "example" in response bodies
• Skip error responses — include at least 400 and 404 where applicable
• Assume auth requirements if the code doesn't specify them — note the uncertainty instead

Example

Input — ASP.NET Core controller:

[ApiController]
[Route("api/[controller]")]
public class UsersController : ControllerBase
{
    /// <summary>Gets a user by their ID.</summary>
    [HttpGet("{id}")]
    public async Task<ActionResult<UserDto>> GetUser(int id) { }

    /// <summary>Creates a new user.</summary>
    [HttpPost]
    public async Task<ActionResult<UserDto>> CreateUser([FromBody] CreateUserRequest request) { }
}

Output:

# Users API — API Reference

> Base URL: `https://api.example.com`
> Authentication: Bearer token

## Users

### GET `/api/users/{id}`

Gets a user by their ID.

**Parameters**

| Name | In | Type | Required | Description |
|------|----|------|----------|-------------|
| `id` | path | integer | ✅ | The user's unique ID |

**Responses**

| Status | Description |
|--------|-------------|
| `200 OK` | Returns the user |
| `404 Not Found` | User not found |

```json
{
  "id": 42,
  "email": "jane@example.com",
  "displayName": "Jane Smith",
  "createdAt": "2026-01-15T10:30:00Z"
}
```

**Example**

```bash
curl -X GET "https://api.example.com/api/users/42" \
  -H "Authorization: Bearer eyJhbG..."
```

---

### POST `/api/users`

Creates a new user.

**Request Body**

```json
{
  "email": "string — the user's email address",
  "displayName": "string — the user's display name",
  "role": "string — user role (admin, member, viewer)"
}
```

**Responses**

| Status | Description |
|--------|-------------|
| `201 Created` | User created successfully |
| `400 Bad Request` | Invalid request body |
| `409 Conflict` | Email already exists |

```json
{
  "id": 43,
  "email": "john@example.com",
  "displayName": "John Doe",
  "createdAt": "2026-02-18T14:00:00Z"
}
```

**Example**

```bash
curl -X POST "https://api.example.com/api/users" \
  -H "Authorization: Bearer eyJhbG..." \
  -H "Content-Type: application/json" \
  -d '{"email": "john@example.com", "displayName": "John Doe", "role": "member"}'
```

Pre-Delivery Checklist

• Every endpoint in the source is documented — none missing, none invented
• All params have correct name, location (path/query/header/body), type, and required status
• Every endpoint has a curl example with realistic data
• Response examples use plausible fake data, not placeholders
• Endpoints are grouped by resource and sorted GET → POST → PUT → PATCH → DELETE
• Auth section matches what the code actually specifies
• Ambiguities are flagged, not silently assumed
• TOC anchors resolve correctly