Api Doc Generator Designer

---
name: api-doc-generator-designer
description: Design generated application programming interface (API) reference documentation from a verified schema or code source, with a check that the source matches the implementation. Split exhaustive generated reference from authored guides and examples; enrich the source, choose a generation toolchain, and version the reference with the API. Use when API docs drift or a reference generator is needed. Do NOT use to design the API contract (api-event-architect), the general docs pipeline (docs-as-code-architect), or the documentation structure (diataxis-doc-organizer).
---

# API Doc Generator Designer

Here, **API** means application programming interface, **CI** means
continuous integration, **PR** means pull request, **SDK** means software
development kit, and **SoT** means source of truth.

## 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 stays aligned to a verified source. Generation alone cannot catch a
stale schema or inaccurate code comments; validate the source against the
implementation. 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 checked against the implementation and 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 from the verified source. Check the schema or
   annotations against implemented behavior in CI; rendering a stale
   source faithfully still produces a stale reference.
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`). When more than one source or toolchain is
   viable, explain the choice in plain terms before asking: why each fits,
   its benefits and drawbacks for this API, and money, setup, and ongoing
   upkeep costs (or what is unknown). Recommend the option supported by the
   API and pipeline evidence, explain why, and name the fact that would
   change the recommendation. If that evidence is missing, ask one discovery
   question first; otherwise ask one clear decision question. A design
   choice alone does not authorize a paid service, installation or publication.
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 alignment checks
   explicit.

Source-of-truth options, the generated-vs-authored split table, schema-
enrichment patterns, and example-validation techniques:
[references/api-doc-sheet.md](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)
Choice, if needed: <plain-language options; why each fits; API-specific pros/cons;
  money/setup/upkeep costs or unknowns; recommendation + why + what could change it;
  one clear decision question>
Versioning:     reference matches API version; deprecations from schema; diff/changelog
Alignment checks: generated reference + source-to-implementation validation
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 source is checked against implemented endpoints and behavior;
      generation alone does not prove it is current.
- [ ] 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.
- [ ] When the user must choose a source or toolchain, the options explain
      their fit, tradeoffs, and money/setup/upkeep costs or unknowns in plain
      terms; a contextual recommendation names its reason and uncertainty,
      followed by one clear question (or one discovery question if needed).
- [ ] 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](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`.