ais-one/novex-kit/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

1. 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)_
 

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

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

 
**Example**
 

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   |
 

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

 
**Example**
 

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

 
---
 
### POST `/api/users`
 
Creates a new user.
 
**Request Body**
 

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

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

 
**Example**
 

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