api-doc-generator-designer

name

api-doc-generator-designer

description

Design GENERATED API reference documentation — reference produced from the API's source of truth (OpenAPI/GraphQL schema, type annotations, docstrings) so it can't drift from the implementation, the split between what to auto-generate (the exhaustive reference) and what to hand-write (guides, examples, overviews), enriching the source of truth so descriptions/examples are single-sourced, the generation toolchain and where it slots into the docs pipeline, try-it/auth/error docs, and versioning the reference with the API. Documents an API that api-event-architect designed; keeps the reference honest by generating it, not hand-maintaining it. Use when generating API reference from a schema or code, keeping API docs in sync, or choosing an API-doc toolchain. Do NOT use to design the API CONTRACT itself (api-event-architect), the general docs pipeline (docs-as-code-architect), or organize docs by type (diataxis-doc-organizer).

API Doc Generator Designer

Purpose

Hand-maintained API reference is wrong the moment the API changes and nobody edits the docs — a parameter gets renamed, the docs still show the old name, and every integrator hits the wall. The fix is to stop maintaining reference by hand: generate it from the API's source of truth so it CAN'T drift. This skill designs that generation — what the source of truth is (OpenAPI/GraphQL schema, type annotations, docstrings), how the exhaustive reference is generated from it, the clean split between generated reference and hand-written guides/examples, enriching the schema so descriptions and examples are single-sourced, the toolchain and its place in the docs pipeline, and versioning the reference with the API. It documents an API that api-event-architect designed; its whole point is a reference that stays honest because it's generated, not typed.

Use When

• Use when: generating API reference from an OpenAPI/GraphQL schema, type annotations, or docstrings.
• Use when: API docs keep drifting from the implementation and you need them generated and in-sync.
• Use when: choosing an API-doc toolchain, or deciding what to auto- generate vs hand-write.
• Use when: designing try-it consoles, auth docs, or a generated error catalog for an API reference.
• Do NOT use when: the task is designing the API CONTRACT itself — routes, versioning policy, envelopes, rate limits, webhooks — that is api-event-architect; this skill DOCUMENTS that contract, it doesn't define it.
• Do NOT use when: the task is the general docs pipeline (generator, build, CI, deploy for all docs) — that is docs-as-code-architect; API reference generation is a slice that plugs into it.
• Do NOT use when: the task is organizing the whole docs corpus by mode — that is diataxis-doc-organizer (reference is one mode; this generates it).

Inputs to Inspect

1. The API's source of truth: is there an OpenAPI/GraphQL schema, typed handlers, or docstrings the reference can generate from — and how complete/accurate is it?
2. The API contract (from api-event-architect outputs where present): routes, versioning/deprecation policy, error envelope, auth model — the reference documents these, it doesn't redefine them.
3. The current API docs: hand-written or generated, how stale, and where they drift from the implementation.
4. The docs pipeline (from docs-as-code-architect where present): how generated reference will build, publish, and version alongside the rest of the docs.
5. The consumers: who reads the reference (external integrators, internal teams) and whether they need try-it consoles, SDK docs, or multiple language examples.

Workflow

1. Establish the source of truth. Reference generates FROM a machine- readable definition — an OpenAPI/GraphQL schema, typed signatures, or structured docstrings. If none exists, creating/adopting one is the real first task; generating from nothing isn't possible.
2. Generate the exhaustive reference. Endpoints/operations, types, parameters (required/optional, formats), responses, and the error catalog — all generated so they match the implementation by construction. This is the drift-killer: generated reference can't fall behind because it IS the schema, rendered.
3. Split generated vs authored. Generate the reference (the complete machinery). Hand-write the quickstart, guides/how-tos, conceptual overviews, and curated examples — generation produces those badly. Map to Diátaxis: reference = generated; tutorials/how-to/explanation = authored (diataxis-doc-organizer places them).
4. Enrich the source of truth, not the output. Descriptions, examples, and metadata live IN the schema/docstrings so they're single-sourced and regenerate automatically. Editing the generated output directly re-creates the drift problem — push enrichments upstream.
5. Design examples, auth, and errors. Request/response examples (ideally validated against the schema so they can't lie), the authentication/authorization docs, and the error catalog generated from the error model (error-taxonomy-designer's codes) rather than hand-listed.
6. Choose the toolchain and slot it in. The generator (OpenAPI→docs, GraphQL doc gen, TypeDoc/Sphinx/etc.), optional try-it/interactive console, and how it builds and publishes within the docs pipeline (docs-as-code-architect).
7. Version the reference with the API. The reference for version X matches version X; deprecations flow from the schema into the docs; a changelog/diff between versions is generated where possible. Coordinate the versioning/deprecation POLICY with api-event-architect.
8. Deliver the generation design in the Output Format, with the source of truth, the generated/authored split, and the sync guarantee explicit.

Source-of-truth options, the generated-vs-authored split table, schema- enrichment patterns, and example-validation techniques: references/api-doc-sheet.md.

Output Format

API-DOC GENERATION DESIGN — <API>
Source of truth: <OpenAPI | GraphQL schema | typed handlers | docstrings> — completeness noted
Generated:      endpoints/operations, types, params, responses, error catalog — from SoT
Authored:       quickstart, guides/how-to, overviews, curated examples (→ diataxis-doc-organizer)
Enrichment:     descriptions/examples live IN the schema/docstrings (single-sourced)
Examples:       request/response validated against schema; auth docs; error catalog from taxonomy
Toolchain:      generator=<...>; try-it console?; plugs into docs pipeline (docs-as-code-architect)
Versioning:     reference matches API version; deprecations from schema; diff/changelog
Sync guarantee: reference generated, never hand-maintained → cannot drift
Boundaries:     contract → api-event-architect; pipeline → docs-as-code-architect;
                corpus org → diataxis-doc-organizer

Validation Checklist

• The reference generates from a machine-readable source of truth; if none exists, adopting one is named as the first task.
• The exhaustive reference (endpoints/types/params/responses/errors) is generated, not hand-written.
• The generated-vs-authored split is explicit (reference generated; guides/examples authored).
• Enrichments (descriptions/examples) live in the source of truth and regenerate — not edited into the output.
• Examples are validated against the schema; auth and the error catalog are documented (errors from the taxonomy).
• The toolchain is chosen and slots into the docs pipeline.
• The reference is versioned with the API; deprecations flow from the schema.
• Contract, pipeline, and corpus-organization concerns are handed to their owning skills.

Gotchas

• Hand-maintained reference is drift waiting to happen: the code changes in one PR, the docs in another (or never), and integrators get burned by a renamed field. Generate reference or accept that it will be wrong.
• Editing the GENERATED output to fix a description re-creates the exact problem — next regen wipes it. Enrichments belong upstream in the schema/ docstrings so they survive regeneration and stay single-sourced.
• Generation is great for reference and terrible for teaching: an auto-generated "guide" is a wall of endpoints with no path through. Generate the machinery; hand-write the narrative.
• Examples that aren't validated against the schema lie as easily as hand-written docs — a stale example is a broken example. Validate them against the source of truth.
• "No schema, just generate from the code comments" often means the comments ARE the missing source of truth and are themselves incomplete; adopting a real schema is frequently the actual work.
• The reference documents the contract; it doesn't define it. Deciding routes, versioning policy, or rate limits inside the doc generator is api-event-architect's job leaking into the wrong place.

Stop Conditions

• The task is designing the API CONTRACT — routes, versioning/deprecation policy, envelopes, rate limits, webhooks → route to api-event-architect; this skill documents that contract.
• The task is the general docs pipeline or organizing the whole corpus → route to docs-as-code-architect or diataxis-doc-organizer.
• No machine-readable source of truth exists and the API is large/ unstable → flag that adopting a schema is the prerequisite; generating accurate reference from nothing isn't possible, and hand-writing it just restarts the drift.
• The versioning/deprecation POLICY the reference must reflect is undefined → obtain it from api-event-architect rather than inventing a policy in the docs.

Supporting Files

• references/api-doc-sheet.md — source-of- truth options, the generated-vs-authored split table, schema-enrichment patterns, example-validation techniques, and versioning/deprecation surfacing.
• evals/evals.json — behavior cases including the drift-killing generation, the enrich-upstream discipline, and the no-schema prerequisite.
• evals/trigger-evals.json — discrimination against api-event-architect (contract vs its reference), docs-as-code-architect, and diataxis-doc-organizer.