用途:为 .NET 项目生成与维护 API 文档,涵盖 DocFX 参考文档、OpenAPI 活文档、文档与代码同步、变更日志和多版本文档。
主要能力:DocFX 从程序集与 XML 注释提取 API 元数据(docfx.json 配置、模板定制、uid 交叉引用、API 过滤);将 OpenAPI 规范作为活文档,嵌入 Scalar 或 Swagger UI,并支持多版本 OpenAPI 文档;文档与代码同步,包括 CI 中以 -warnaserror:CS1591 校验注释完整性、断链检测、PR 自动构建文档;API 变更日志模式,记录破坏性变更、迁移指南与已弃用 API 跟踪;多版本 API 文档(版本选择器、多版本维护、URL 模式)。
使用方式:安装 DocFX 可用 dotnet tool install -g docfx 或本地工具清单;生成元数据用 docfx metadata docfx.json,构建站点用 docfx build docfx.json --warningsAsErrors。OpenAPI 侧通过 AddOpenApi、MapOpenApi 与 MapScalarApiReference 或 UseSwaggerUI 暴露文档,也可在构建时导出规范。
适用场景:.NET 库与服务的 API 参考站点、需要随代码演进的接口文档、多版本 API 维护、破坏性变更与迁移说明。
限制:版本假设为 DocFX v2.x、OpenAPI 3.x(.NET 9+ 内置)、.NET 8.0+ 示例基线。XML 注释语法、OpenAPI 生成配置、文档站点部署流水线、平台选型、变更日志工具与 SemVer 版本策略均不在本技能范围内,分别参见相关技能。具体收费、价格与平台支持暂未提供。