API Reference Generation

Distinct from Documentation Frameworks (Fumadocs, Starlight, etc.). This is about the generated reference part of docs — derived from your code's types and comments.

TypeScript-first

• ★ TypeDoc — the standard for generating reference from TS source. HTML, JSON, Markdown plugins. Default.
• ★ @microsoft/api-extractor — produces a clean .d.ts rollup + an api.json for further processing. Default for libraries that publish to npm.
• @microsoft/api-documenter — turns api-extractor output into docs (Markdown / Yaml).
• tsdoc — Microsoft's standard for TS doc comments; @param, @returns, etc.
• dts-bundle-generator — bundles .d.ts into one file for distribution.
• tshy, tsup — library bundlers that produce types as a side effect.
• @arethetypeswrong/cli — verifies your published types resolve in every consumer.

Markdown-output integration

• ★ typedoc-plugin-markdown — TypeDoc plugin that emits Markdown; pair with Documentation Frameworks.
• ★ Fumadocs fumadocs-typescript — direct TypeDoc-style generator that integrates with Fumadocs MDX. Use this if your site is on Fumadocs.
• docusaurus-plugin-typedoc — same idea for Docusaurus.
• VitePress vitepress-jsdoc / vitepress-typedoc — for VitePress.
• Starlight's typedoc plugin — for Astro Starlight.

JSDoc / non-TS projects

• JSDoc — the original; produces HTML.
• better-docs — JSDoc theme.
• documentation.js — different generator; nicer defaults.
• API Blueprint / aglio — for REST APIs; older.

OpenAPI / GraphQL reference

• See OpenAPI Tooling — Scalar, Stoplight Elements, Redoc.
• See GraphQL Codegen — for typed GraphQL clients; reference often via SpectaQL or Magidoc.
• SpectaQL — GraphQL static-doc generator.
• Magidoc — modern GraphQL reference site generator.

SDK reference patterns

• Stainless — generates SDKs and docs from OpenAPI; commercial.
• Speakeasy — same niche; commercial.
• Fern — same niche; commercial; OpenAPI-input.
• Scalar Galaxy / Scalar SDKs — newer hosted offerings.

What good reference looks like

• ★ Linkable types — clicking a type takes you to its definition.
• Code examples per function — extracted from your test files via TSDoc tags or hand-written.
• Search — Algolia / Pagefind / Orama (see Search).
• Type aliases inlined — readers shouldn't bounce 5 hops to understand a parameter.
• Stability / since tags — @since, @deprecated, @experimental.
• Cross-reference between guides and reference — your handwritten guides link into reference; reference links back to relevant guides.

Patterns to know

• Comment as you go — TSDoc comments paid up at build time; retrofitting is painful.
• One source of truth — don't write JSDoc that duplicates types. Let TS infer; comment the why.
• Examples in tests — extract via doc-test patterns or simply link to GitHub.
• Two surfaces in one site — handwritten guides + auto-generated reference. Fumadocs handles this cleanly.
• Version your reference — every published version of a library should have its own reference snapshot.

Pick this if…

• Default TS library reference: TypeDoc + typedoc-plugin-markdown + your docs framework.
• You're on Fumadocs (like this site): fumadocs-typescript.
• Publishing a library to npm: add @arethetypeswrong/cli to CI.
• OpenAPI / SDK docs: Scalar (or Stainless / Speakeasy / Fern if you want the SDK too).
• GraphQL reference site: Magidoc.