api-doc

从 TypeSpec 定义生成单文件、自包含的 HTML API 文档。

能力

• 从 TypeSpec (.tsp) 文件解析 API 定义
• 自动生成 cURL 示例
• 参数表格（类型、约束、必填状态）
• 版本标签（@added / @removed）
• 条件必填字段（@requiredIf）
• 条件选填字段（@optionalIf）
• 枚举成员说明（enum @doc 自动渲染）
• 交互式请求/响应示例（@opExample）
• Markdown 片段注入（header / footer）
• 语法高亮（highlight.js）
• 主题支持（内置 light 主题，支持自定义 CSS）
• RocketMQ 消息定义（@typespec/events @events union）
• 消息结构文档（Topic + Payload 属性表）
• HTTP 接口与消息的视觉区分（MQ 标签、紫色边框）

使用

必须使用 bun，禁止使用 npm。 执行前先确认依赖已安装：

test -d node_modules || bun install

bun run scripts/index.ts <input-dir> [output] [--theme <name>] [--theme-file <path>]

• <input-dir> — 包含 .tsp 文件的目录（必填）
• [output] — 输出文件路径（可选，默认 <input-dir>/../<dirName>-<revision>.html）

选项

示例

# 默认输出
bun run scripts/index.ts ./samples/tms

# 指定输出路径
bun run scripts/index.ts ./samples/tms ./output.html

# 使用 light 主题
bun run scripts/index.ts ./samples/tms --theme light

参考文档