types2docs

types2docs

编写 TypeScript API 文档通常意味着手动维护一份 Markdown 参考文档，并确保它与类型定义同步，但两者往往会逐渐偏离。types2docs 采用了另一种方式：你提供已有的声明事实——每个声明的名称、它是接口、类型别名、枚举还是函数、它的文档注释，以及特定类型的内容（成员、别名的右侧定义或函数签名）——它就仅根据这些事实，以固定布局生成参考文档。不会凭空添加任何内容，也不会改写任何内容：文档中的每个字符串都原样来自你的输入。

布局始终不变。文档以 # 标题行开头，除非你提供了 title，否则标题为“API Reference”；随后按你提供的顺序，为每个声明生成一个章节。每个章节都有一个以声明名称为标题的 ## 标题；如果存在文档文本，就将其作为单独的段落；接着是一行 Kind: <kind>，然后是对应类型的内容。接口会渲染为表格，每个成员占一行，包含成员名称、类型文本，以及成员是否为必填项（optional 缺失或为 false 时为 yes，为 true 时为 no）；表格后面会为每个有文档注释的成员单独生成一行，汇总其文档注释。枚举会为每个成员生成一行；如果存在值，则附加 = <value>，如果存在成员文档注释，则也会附加该注释。没有成员的接口或枚举会渲染为单独一行 (no members)。类型别名和函数都会渲染为围栏 ts 代码块：类型别名的格式为 type <name> = <definition>；函数则使用原样提供的签名。段落和章节之间恰好用一个空行分隔，文档末尾恰好有一个换行符。除 Markdown 外，结果还包含统计信息：提供的声明数量、每种类型的数量，以及接口和枚举的成员总数。

类型规则是结构性的，违反规则会导致验证错误，而不是由渲染方式决定。接口和枚举必须提供 members，类型别名和函数则禁止提供 members。类型别名必须提供 definition，其他类型均禁止提供；函数必须提供 signature，其他类型均禁止提供。在成员内部，接口成员必须提供 type，枚举成员则禁止提供 type；value 仅适用于枚举成员；枚举成员禁止使用 optional。两个声明名称相同，或同一声明中的两个成员名称相同，也会报错。每个验证错误都会指出出错路径——例如 types[1].members[0].type is required for interface members——且不会生成部分文档。未知的额外字段会被忽略，包括声明和成员内部的字段。

CLI

npx @reneturcios/types2docs render --input args.json
npx @reneturcios/types2docs --version

args.json 包含完整的参数对象：

{
  "title": "Widget API",
  "types": [
    {
      "name": "Widget",
      "kind": "interface",
      "doc": "A widget in the catalogue.",
      "members": [
        { "name": "id", "type": "string", "doc": "Unique identifier." },
        { "name": "label", "type": "string", "optional": true }
      ]
    },
    {
      "name": "WidgetId",
      "kind": "type",
      "definition": "string & { readonly brand: \"WidgetId\" }"
    },
    {
      "name": "Colour",
      "kind": "enum",
      "members": [
        { "name": "Red", "value": "\"red\"" },
        { "name": "Blue", "value": "\"blue\"", "doc": "The calm one." }
      ]
    },
    {
      "name": "makeWidget",
      "kind": "function",
      "signature": "function makeWidget(id: WidgetId): Widget"
    }
  ]
}

渲染结果以 JSON 格式输出：

{
  "markdown": "# Widget API\n\n## Widget\n\nA widget in the catalogue.\n\nKind: interface\n\n| Member | Type | Required |\n| --- | --- | --- |\n| id | string | yes |\n| label | string | no |\n\n- `id` — Unique identifier.\n\n## WidgetId\n\nKind: type\n\n```ts\ntype WidgetId = string & { readonly brand: \"WidgetId\" }\n```\n\n## Colour\n\nKind: enum\n\n- `Red` = \"red\"\n- `Blue` = \"blue\" — The calm one.\n\n## makeWidget\n\nKind: function\n\n```ts\nfunction makeWidget(id: WidgetId): Widget\n```\n",
  "counts": {
    "types": 4,
    "interfaces": 1,
    "type_aliases": 1,
    "enums": 1,
    "functions": 1,
    "members": 4
  }
}

退出代码：成功时为 0，运行时错误时为 1（包括无法读取或无效的输入文件，以及无效输入），用法错误时为 2。

MCP 服务

npx -y @reneturcios/types2docs mcp

MCP 客户端配置：

{
  "mcpServers": {
    "types2docs": {
      "command": "npx",
      "args": ["-y", "@reneturcios/types2docs", "mcp"]
    }
  }
}

工具

• render_api_reference — 根据调用方提供的 TypeScript 类型 声明（接口、类型别名、枚举和函数），以固定的确定性布局 渲染 Markdown API 参考文档。不会凭空编造任何内容；每个 字符串都来自输入。

  • types（数组，必填，至少 1 项）— 要记录的类型声明， 按文档顺序排列；每项包含：
    • name（字符串，必填，非空）— 声明的 名称
    • kind（字符串，必填）— 以下值之一："interface"、 "type"、"enum" 或 "function"
    • doc（字符串，可选）— 声明的文档注释 文本
    • members（数组）— interface 和 enum 必填， type 和 function 禁止使用；每项包含：
      • name（字符串，必填，非空）— 成员 名称
      • type（字符串）— 成员类型文本；interface 成员 必填，enum 成员禁止使用
      • value（字符串，可选）— 枚举成员值 文本（仅限 enum 成员）
      • optional（布尔值，可选）— 成员是否为可选项 （仅限 interface 成员）；缺省表示 false
      • doc（字符串，可选）— 成员的文档注释 文本
    • definition（字符串）— 类型别名的右侧内容， 原样提供；kind 为 "type" 时必填， 其他情况禁止使用
    • signature（字符串）— 函数签名， 原样提供；kind 为 "function" 时必填，其他情况禁止使用
  • title（字符串，可选）— 文档标题； 默认值为 "API Reference"；允许使用空字符串，渲染结果为 #

  返回 {markdown, counts}，其中 markdown 是 渲染后的文档，counts 是 {types, interfaces, type_aliases, enums, functions, members} （键的顺序如上）。

Docker

docker run -i ghcr.io/cloudcorprecords/types2docs
docker run --rm -v "$PWD:/w" ghcr.io/cloudcorprecords/types2docs render --input /w/args.json

开发

npm install
npm run build   # tsc -> dist/
npm test        # tsx --test test/*.test.ts (pure local, no network)
npm run dev     # run the CLI from source

许可证

MIT — Copyright (c) 2026 Rene Turcios