技能使用指南

documentation-generation（文档生成）Skill 是什么？能自动生成 API 文档吗？

文档生成Skill（documentation-generation）帮你用 JSDoc、TypeDoc、OpenAPI、Storybook、Docusaurus 等工具产出 API 文档、README、变更日志与开发者指南。坚持文档即代码、单一来源真相、示例优于解释，覆盖从注释生成到死链检查的完整链路。了解它如何降低文档维护成本、提升团队协作效率。

文档生成Skilldocumentation-generation
8 个章节 约 16 分钟阅读 AI 智能生成

文档生成Skill：让代码注释自动长出可维护的技术文档

  • 它是什么：文档生成（documentation-generation）是一个面向技术写作场景的 AI 技能，专注产出 API 文档、组件库文档、README、架构决策记录（ADR）、变更日志和开发者指南。
  • 它怎么做：强调「文档即代码」，优先从 JSDoc/TSDoc 注释、OpenAPI 注解、GraphQL Schema 等源头生成文档，而不是另外手写一套容易过期的说明。
  • 它的覆盖范围：从单函数注释，到 README、CHANGELOG，再到 VitePress / Docusaurus 文档站点与 CI 链接检查，形成完整链路。
  • 适合谁用：后端/前端开发者、开源维护者、技术写作者，以及需要交付对外 API 文档的团队。
  • 核心收益：把「写文档」从一次性体力活，变成可复用、可审查、可自动检查的工程流程。

1. 该技能叫什么？如何一键安装 AI 技能提升开发效率？

基本信息

项目 内容
技能中文名 文档生成
技能英文名 documentation-generation
技能ID 11273

它解决什么问题

大部分团队的文档困境并不是「不会写」，而是三个现实问题：

  1. 写不动：API 一多，手写参考文档的成本急剧上升，往往拖到发版前才临时补。
  2. 对不上：代码改了，文档没改，读者照着旧文档调用接口直接报错。
  3. 找不到：README 只有一句「TODO」，新人上手全靠问人，重复答疑消耗团队时间。

文档生成Skill 的思路是把文档工作「前置」到代码里：用标准的注释与配置格式（JSDoc/TSDoc、OpenAPI @swagger 注解、GraphQL SDL 描述、typedoc.json、docusaurus.config.js 等）作为单一来源真相，再由技能辅助生成、补全和校验文档内容。它同时会给出 README、CHANGELOG、CONTRIBUTING 的成熟模板结构，以及文档清单（Checklist），避免遗漏 LICENSE、配置表、弃用说明等容易被忘掉的项。

「一键安装」的思路与步骤

安装的具体入口、命令和账号要求，会随你使用的 AI 客户端或技能市场而变化，本文不臆造命令，请以官方说明为准。通用流程如下：

  1. 确认前提：你已能正常使用一个支持「技能（Skill）」机制的 AI 编程助手或客户端；本地项目具备基本的代码仓库与 Node.js 工具链（因为 JSDoc、TypeDoc、Docusaurus 等生态均基于 npm）。
  2. 找到技能入口：在客户端的技能市场 / 技能库 / 插件中心中搜索技能名「文档生成」或英文名 documentation-generation；若支持按 ID 检索，可直接搜索技能 ID 11273。
  3. 完成安装与授权：按页面提示确认安装，并授予技能读取项目目录的权限（生成文档需要读取源码与注释）。
  4. 验证是否生效：在对话中直接提出一个具体请求，例如「帮我为 src/routes/users.ts 里的接口补全 @swagger 注释，并生成对应的 OpenAPI schema 定义」。若技能已生效，返回内容应包含结构化的 OpenAPI/JSDoc 片段；若没有反应，通常是技能未启用或工作目录权限未开放，回到第 2、3 步检查即可。

2. 该技能的主要功能和特点

  • API 文档生成（REST）：按 OpenAPI/Swagger 规范补全接口的 summary、description、parameters、responses 以及 components/schemas 复用结构，并配套 swagger-jsdoc + swagger-ui-express 的挂载方式，把文档暴露为可交互的 /api-docs 页面。
  • API 文档生成（GraphQL）：通过 SDL 中的 """...""" 描述块为 type、input、Query 字段补充说明与 @example 查询示例，配合 GraphQL Playground 获得交互式文档。
  • TypeScript 代码文档：基于 TypeDoc 流程输出接口与类的说明，支持 @param、@returns、@throws、@example 等标签，并提供 typedoc.json 配置（入口、输出目录、excludePrivate、includeVersion、Markdown 插件）。
  • README 模板化产出：输出包含项目简介、功能列表、快速开始命令、安装、使用示例、API 参考链接、环境变量配置表、贡献指引与许可证的完整 README 结构。
  • CHANGELOG 与发布说明：遵循 Keep a Changelog 分类（新增/更改/弃用/移除/修复/安全）与语义化版本，并强调为破坏性变更附迁移指南（前后代码对照）。
  • 文档站点搭建：覆盖 VitePress（首页 Hero、features、code-group 多包管理器安装块、导航与侧边栏 themeConfig）与 Docusaurus（docusaurus.config.js、presets、navbar、editUrl）两种主流方案。
  • 质量与自动化检查：提供 GitHub Actions 工作流示例做 Markdown 死链检查，以及从 Markdown 中提取代码块并实际执行、确保示例不会「跑不起来」的测试思路。
  • 可执行的文档清单：分为「基本文档 / 代码文档 / 质量 / 维护」四组勾选项，把「文档写完没」变成可验收的条目。

和普通工具比强在哪：TypeDoc、Swagger UI 这类工具只负责「把注释渲染成页面」，注释写不写、写得好不好、有没有跟上代码变化，工具不管；而文档生成Skill 补的正是这一段——从内容生成、结构规范到质量检查与持续维护的完整方法论。

3. 如何使用该技能？

以下步骤以实际开发中最常见的三种任务为例，示例可直接参考改写。

步骤 1：明确告诉技能「受众 + 载体 + 来源文件」

输入示例：

请为 src/services/userService.ts 生成 TypeDoc 风格的注释。受众是外部接入方，需要包含 @example 与 @throws。

步骤 2：让技能产出「源头注释」，而不是直接产出成品文档

文档生成Skill 的核心原则是「单一来源真相」，因此它会优先给出可落进代码的注释。例如它会输出类似结构：

/**
 * 通过 ID 查找用户
 * @param id - 用户 ID
 * @returns 用户对象；未找到时返回 null
 * @throws {ValidationError} 当 id 格式非法时
 * @example
 * const user = await userService.findById('123');
 */
async findById(id: string): Promise<User | null> { /* ... */ }

步骤 3：配置生成器并执行

让技能同时给出配置文件与命令，例如 typedoc.json 中的 entryPoints、out、excludePrivate、includeVersion 字段，然后执行 npx typedoc 输出到 docs/ 目录。REST 接口则用 swagger-jsdoc 读取 apis: ['./routes/*.ts'] 并挂载 Swagger UI。

步骤 4：补充项目级文档

  • 让它生成 README 骨架，并填入真实的环境变量表（变量名、描述、默认值）。
  • 让它按 Keep a Changelog 格式整理本次迭代的「新增 / 更改 / 修复」，破坏性变更必须附迁移对照代码。

步骤 5：接入自动化检查

让技能产出 .github/workflows/docs.yml，在 push 和 pull_request 时运行 Markdown 链接检查；同时补充「提取文档示例代码并运行」的测试用例，保证示例始终可执行。

步骤 6：对照文档清单收尾

最后让技能按「基本文档 / 代码文档 / 质量 / 维护」四组清单逐项自检，输出还缺什么。这一步能明显减少漏项。

输出说明：技能的产出通常包含「可直接提交的代码注释片段 + 配置文件 + 命令 + 检查清单」四类内容，你需要把它们落到仓库中并提交评审，文档才会真正随代码演进。

4. 同类型竞品对比分析

方案名称 定位 核心功能 安装/使用门槛 适用场景 优势与不足
文档生成Skill（documentation-generation） 文档生产的「方法论 + 内容生成」助手 API 文档、组件文档、README、CHANGELOG、ADR、文档站点、自动化检查 需在支持技能机制的 AI 客户端中安装，入口与命令以官方说明为准 从零建立文档体系、补齐历史欠账、统一团队文档规范 优势：覆盖全链路且强调可维护性；不足：产出仍需人工审校后合入仓库
TypeDoc / JSDoc 原生工具链 代码注释到文档站点的渲染器 解析注释、生成 HTML/Markdown 参考 属于 npm 生态，需自行配置入口与插件 纯 TypeScript 库的 API 参考 优势：成熟稳定、与语言绑定紧；不足：不会帮你「写出」注释内容，对非代码文档无覆盖
Swagger UI / OpenAPI 生态 REST API 契约与交互式文档 规范定义、在线调试、Schema 复用 需编写 OpenAPI 描述或注解 对外 REST 接口、需要在线试调的 API 优势：契约清晰、可交互；不足：注解体积大，手写维护成本高，非 API 文档不管
Docusaurus / VitePress 静态文档站点框架 导航、侧边栏、版本化、主题定制 需要前端工程能力与构建配置 产品官网式文档站、多版本文档 优势：呈现效果与扩展性好；不足：只解决「展示层」，内容从哪来仍需自己解决
手工撰写 / 传统 Wiki 人工维护的知识库 自由编写、富文本编辑 门槛最低 制度流程、非技术类文档 优势：灵活；不足：极易与代码脱节，缺少死链与示例校验，难以版本化审查

选型建议：工具类方案解决「渲染」，文档生成Skill 解决「内容与流程」。二者不是替代关系——最有效的组合是用技能产出规范注释与文档骨架，再用 TypeDoc / Swagger UI / Docusaurus 渲染发布。

5. 该技能的典型应用场景与实际体验情况

场景一：后端团队补齐对外 API 文档

角色：后端工程师，手上 30+ 个 REST 接口，对外交付前必须提供文档。 痛点：手写 OpenAPI 描述工作量巨大，且极易与实现不一致。 使用方式：让技能逐个路由文件补 @swagger 注释与可复用的 components/schemas，再挂载 Swagger UI。 实际体验：上手难度低，因为技能给的是「填进代码里的注释」而非抽象建议，落地阻力小。注意事项：Schema 复用要人工把关，避免同一实体出现多份互相矛盾的定义。

场景二：组件库与内部工具的文档化

角色：前端团队 / 平台组。 痛点：组件属性靠口口相传，新人反复问「这个参数默认值是多少」。 使用方式：按 Storybook 或 JSDoc/TSDoc 路径补组件说明与示例，把 @example 写成可直接复制运行的代码。 实际体验：效果最好的部分是可运行示例——「示例优于解释」原则在这里体现明显。注意事项：示例代码要纳入 CI 测试，否则半年后一定会失效。

场景三：开源项目维护者完善仓库门面

角色：个人开源作者。 痛点：README 只有安装命令，没有使用示例、配置表和贡献指引，Issue 里全是重复提问。 使用方式：套用技能提供的 README 模板补齐功能列表、快速开始、配置表、CONTRIBUTING 与 LICENSE；用 CHANGELOG 模板整理版本记录。 实际体验：见效最快、收益最直接，README 完整度提升后重复提问明显减少。注意事项：环境变量表必须填真实默认值，不要留占位符。

场景四：架构决策与文档站点长期维护

角色：Tech Lead / 技术写作者。 痛点：架构决策只存在于会议记录里，文档站上线后很快过期。 使用方式：用 ADR 记录决策背景与取舍；用 VitePress 或 Docusaurus 搭站；接入死链检查工作流与文档清单自检。 实际体验：这部分属于「长期价值大于即时效果」的能力，短期不显眼，但一旦形成「文档随 PR 一起评审」的习惯，过期文档问题会显著缓解。注意事项：CI 检查需要一次性配置投入，建议先从死链检查这一项开始。

6. 该技能能为用户带来的价值

  • 效率提升：把「从零构思文档结构」变成「审阅并修正已有结构」，README、CHANGELOG、API 注释这类模板化程度高的工作，节省的主要是结构化构思与格式对齐的时间，而不是简单的打字时间。
  • 门槛降低：不熟悉 OpenAPI 规范、TypeDoc 标签体系或 Keep a Changelog 约定的开发者，也能产出符合行业惯例的文档，减少「格式返工」。
  • 一致性收益：统一的注释风格、统一的分组（新增/更改/修复/安全）、统一的配置表格式，让多人协作的文档读起来像一个人写的。
  • 可量化的长期收益：死链检查与示例测试把「文档腐烂」变成 CI 可以拦截的问题；文档清单把「文档是否完成」变成可验收项；二者共同降低了新人上手与跨团队对接的沟通成本。
  • 资产化：当文档从代码注释自动生成并纳入版本控制，它就变成了可审查、可回溯的工程资产，而不是某个人的记忆。

7. 常见问题 FAQ

Q1：这个技能怎么安装？需要付费吗？

A：在支持技能机制的 AI 客户端中搜索「文档生成」或英文名 documentation-generation（部分平台支持按技能 ID 11273 检索）后按提示安装即可。具体安装入口、命令以及是否收费，取决于你所使用的平台，请以官方说明为准。

Q2：它能直接生成一份完整的文档网站吗？

A：它能生成搭建文档站所需的配置与内容骨架，例如 VitePress 的首页 Hero、导航与侧边栏配置，或 Docusaurus 的 docusaurus.config.js 与 presets 结构，以及各页面 Markdown 内容。但站点部署、域名与托管仍需你按所选框架的流程完成。

Q3：生成的文档还需要人工修改吗？

A：需要。技能负责结构、规范与初稿，事实性内容（真实默认值、真实错误码、真实业务语义）必须由最了解代码的人确认。建议把文档变更和代码变更放在同一个 PR 中评审。

Q4：适合谁用？小项目有必要吗？

A：适合后端/前端开发者、开源维护者、技术写作者和需要对外交付 API 的团队。小项目同样值得用，但可以只取最小集：一份能跑的 README + 公共 API 的注释 + 一个 CHANGELOG，不必一上来就搭文档站。

Q5：和 TypeDoc、Swagger UI、Docusaurus 冲突吗？该怎么选？

A：不冲突，是上下游关系。文档生成Skill 解决「内容从哪来、怎么保持新鲜」，TypeDoc / Swagger UI / Docusaurus 解决「怎么渲染发布」。推荐组合使用：先用技能产出规范注释与文档骨架，再用这些工具生成站点。