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

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:

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

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

    > 📊 **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:

    > ⚠️ **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.

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.