SuperAPI AI 工具集

documentation-generation

写作与研究

查看项目

更新于 10-15 21:46

技能介绍

该技能聚焦自动化文档生成模式,提供从代码注释到文档站点的一整套实践参考。

用途:为项目创建和维护高质量文档,让文档与代码保持同步。

主要能力:

  • TSDoc / JSDoc 标准:覆盖函数、接口、组件三类文档写法,包含 @param、@returns、@throws、@example、@remarks、@defaultValue、@see 等标签用法。
  • OpenAPI:通过 @ts-rest/open-api 的 generateOpenApi 从类型契约生成文档,并可用 swagger-ui-react 集成 Swagger UI 展示,路由示例为 /api/docs 与 /api/openapi.json。
  • README 模板:给出项目名、特性、快速开始、安装、用法、API 参考、配置表、贡献与许可证等常见区块结构。
  • TypeDoc:提供 typedoc.json 配置示例(entryPoints、out、plugin、githubPages 等),以及 docs 与 docs:watch 脚本。
  • Docusaurus:给出文档站点目录结构与 docusaurus.config.js 配置示例。

使用方式:编写符合 TSDoc/JSDoc 的注释,配置 TypeDoc 或 OpenAPI 生成器,运行 npm run docs 等命令生成文档;可通过 Husky pre-commit 钩子执行 npx typedoc --emit none 校验文档编译,并用 GitHub Actions 工作流构建并部署到 GitHub Pages。

适用场景:公共 API、复杂逻辑、配置项与破坏性变更的文档化,文档站点搭建和 CI 自动化。

限制:资料未说明具体收费、价格、平台兼容性或效果保证;部分配置需按实际项目调整,示例中的地址和令牌需替换为真实值。