# API Documentation Doc

> Generate professional API Documentation as a formatted Word (.docx) file — API overview, authentication, endpoint catalog, request/response schemas, error handling, rate limiting, versioning, and example requests. Use this whenever someone asks for "API docs," "API reference," "endpoint documentation," or wants a standalone document describing a system's API contract (as distinct from the system's overall architecture or database schema, which have their own companion skills). Part of an enterprise handover documentation suite (see also: project-overview-doc, architecture-document, high-level-design, operations-deployment-guide, support-runbook, database-design, release-maintenance-guide) but fully usable standalone.

- Skill: `vedkathe/api-documentation-doc` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add vedkathe/api-documentation-doc`
- Raw SKILL.md: https://api.skillmd.com/api/skills/vedkathe/api-documentation-doc/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: VedKathe (https://skillmd.com/u/vedkathe)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/vedkathe/api-documentation-doc

---


# API Documentation Generator

Produce a single `.docx` document describing a system's API contract in
enough detail that another team could integrate against it without asking
questions. If a machine-readable spec (OpenAPI/Swagger) already exists, this
document should summarize and link to it rather than duplicate every field —
the `.docx` is for human-readable context, conventions, and examples.

## Sections (in this order)

Cover page, Version History, Document Approval, Revision Log, and TOC are
automatic — your `sections` array starts at "1. API Overview".

| # | Section | Content | Diagram? |
|---|---|---|---|
| 1 | API Overview | Base URL(s), versioning scheme (e.g., `/v1/`), auth method, content-type conventions | |
| 2 | Authentication & Authorization | How clients authenticate (API key, OAuth2, JWT), scopes/permissions model | |
| 3 | Endpoint Catalog | Table: Method, Path, Description, Auth Required — the full list | **API Flow Diagram** — a typical request's path through gateway/services |
| 4 | Request & Response Schemas | Key schemas per resource, or a link to the full OpenAPI spec if one exists | |
| 5 | Error Handling | Standard error response format; table of error codes and meanings | |
| 6 | Rate Limiting & Throttling | Limits per client/tier, headers used, behavior when exceeded | |
| 7 | Versioning & Deprecation Policy | How breaking changes are introduced, deprecation notice period | |
| 8 | Webhooks / Callbacks | If applicable: events, payload format, retry behavior | |
| 9 | Example Requests | A few realistic curl or code examples covering common operations | |
| 10 | Appendix | OpenAPI spec link, Postman collection link, related documents | |

If the API has no webhooks/callbacks, keep the heading and mark it "Not
applicable for this API" rather than deleting the section — consistency
across generated documents matters more than omitting an empty section.

## Diagram Policy

**Applies to the `.docx` path only** — Markdown embeds Mermaid source
directly instead of rendering anything (see "Output Format" below).

Prefer a real Mermaid diagram — rendered via `mmdc` and embedded with
`B.diagramImage()` — over `diagramPlaceholder()`, but only once you have
concrete structure to draw (real names, not "TBD"). Read
`references/diagram-generation.md` when you're actually about to render one
— it has the full build order, the bundled config
(`assets/mermaid-config.json`), the exact `mmdc` flags, and token-saving
tips. Skip it entirely if this document ends up needing no diagrams.

## Missing Information Policy

Never invent endpoints, parameters, or response fields you have no basis for
— a fabricated field is actively harmful here, since another team may write
integration code against it. Use `toBeCompleted("...")` for endpoints or
sections you lack real input for, explaining what's needed (e.g., "point me
at the OpenAPI spec or route definitions"), and still generate everything
else.

## Output Format

Ask the user which output format they want, unless they've already said so in
this request (e.g., "as a docx", "in markdown," "just give me an .md file") —
a quick single-choice question is enough, don't block on it otherwise:

- **Word document (.docx)** — the default assumption if the person hasn't
  specified and their context suggests a formal deliverable. Follow "Using
  the builder" below.
- **Markdown (.md)** — no script needed, write the file directly. Use these
  conventions so it stays structurally equivalent to the docx version:

  - Front matter: instead of a cover page, open with the title as an `#`
    heading, the project name as an italic subtitle line, then a metadata
    table instead of separate Version History / Approval / Revision Log
    tables:

    ```markdown
    # API Documentation
    *Acme Order Platform*

    | Field | Value |
    |---|---|
    | Version | 0.1 |
    | Author | Jane Doe |
    | Date | 2026-07-19 |
    | Status | Draft |
    | Approved By | Jane Doe (Tech Lead) |
    ```
  - Headings: `#`/`##`/`###`/`####` matching the same section levels used in
    the table above — don't flatten everything to one level, that's what
    keeps the document skimmable and consistent with the docx version.
  - Tables: standard Markdown tables.
  - Diagrams — unlike the `.docx` path, don't render or embed an image here.
    Write the actual Mermaid source directly in a fenced code block; GitHub,
    GitLab, Obsidian, and most modern Markdown viewers render `mermaid` code
    blocks natively, so this is a real diagram, not a placeholder:

    ````markdown
    ```mermaid
    flowchart TD
        A[Client] --> B[API Gateway]
        B --> C[Order Service]
        C --> D[(Database)]
    ```
    ````
    Only fall back to a text placeholder if you don't yet have concrete
    enough detail to draw something real (mirrors `toBeCompleted` above):
    ```markdown
    > 📊 **DIAGRAM PLACEHOLDER — TO BE COMPLETED**
    > Not enough detail yet to draw the System Architecture Diagram — need
    > the actual component names and how they connect.
    ```
  - "To be completed" callout — same blockquote treatment:

    ```markdown
    > ⚠️ **TO BE COMPLETED**
    > Explanation of what input is needed to fill this in.
    ```
  - Save as `API_Documentation.md` instead of `API_Documentation.docx`.

## Workflow

Ask the output format first (see "Output Format" above). For Markdown, skip straight to writing the file using those conventions — the numbered steps below describe the `.docx` path.

1. Gather what's available — ideally an OpenAPI/Swagger spec or the actual
   route definitions in the codebase; otherwise ask for the endpoint list.
2. Draft each section as data using the builder functions below.
3. Build with `scripts/docx_builder.js`.
4. Skip PDF conversion by default — `docx_builder.js` is already tested and
   hardened (table widths and text alignment are enforced at the library
   level), so routine generations don't need a re-render just to confirm it
   worked. Only convert to PDF and view it if the user explicitly asks for
   visual verification, or if something about this generation is unusual
   (e.g., a new kind of content the library hasn't handled before, or a
   reported rendering problem). When you do need it: `soffice --headless
   --convert-to pdf <file>.docx` (or `libreoffice --headless ...`), then
   `pdftoppm -jpeg -r 100 <file>.pdf page` and view the images.
5. Save to `/mnt/user-data/outputs/API_Documentation.docx` (or `.md` if that's the chosen format) and present it.

## Using the builder (for the .docx path)

This library requires the `docx` npm package. Before running any script,
check it's available with `node -e "require('docx')"`; if that fails, install
it with `npm install docx` in the working directory first — don't assume it's
pre-installed, since that varies by environment.

```javascript
const B = require("./scripts/docx_builder.js");

const sections = [
  B.h1("1. API Overview"),
  B.para("Base URL: https://api.acme.com/v1/. All requests and responses use JSON. Auth via Bearer token."),

  B.h1("3. Endpoint Catalog"),
  B.table(["Method", "Path", "Description", "Auth Required"],
    [
      ["GET", "/v1/orders", "List orders for the authenticated account", "Yes"],
      ["POST", "/v1/orders", "Create a new order", "Yes"],
    ],
    [1300, 2600, 3600, 1700]),

  // Prefer B.diagramImage(path, {caption}) with a real mmdc render when
  // possible (see "Diagram Policy" above) — diagramPlaceholder() is the fallback:
  B.diagramPlaceholder({
    name: "API Flow Diagram",
    purpose: "Show a typical request's path from client through gateway to backend services.",
    recommendedContent: ["Client", "API Gateway", "Auth Service", "Order Service", "Database"],
  }),

  B.h1("5. Error Handling"),
  B.table(["Code", "Meaning"], [["400", "Validation error — see `errors` array in response body"]], [1800, 7200]),

  B.h1("7. Versioning & Deprecation Policy"),
  B.toBeCompleted("Versioning/deprecation policy wasn't provided — ask whether the API follows a formal deprecation window."),
];

await B.buildDocument("/mnt/user-data/outputs/API_Documentation.docx", {
  docLabel: "API Documentation",
  title: "API Documentation",
  subtitle: "Acme Order Platform",
  versionHistory: [["0.1", "2026-07-19", "Jane Doe", "Initial draft"]],
  approvers: [["Jane Doe", "Tech Lead", "", ""]],
  revisionLog: [],
  sections,
});
```

Available functions: `h1`/`h2`/`h3`/`h4`, `para`, `bullets`, `table(headers,
rows, widths)`, `pageBreak`, `toBeCompleted(explanation)`,
`diagramPlaceholder({name, purpose, recommendedContent, notes})`, and
`buildDocument(path, options)`. Always use heading functions for titles so
Word's Table of Contents and Navigation Pane work correctly.

## Success Criteria

An engineer on a different team should be able to integrate against this API
using only this document — correct base URL, auth, endpoints, error format,
and enough examples to get a first successful call working.