ci/cd中文档自动生成与更新需将其视为“一等公民”，通过配置驱动、工具适配（如phpdocumentor、springdoc、schemaspy、doctoc、deepwiki）、流水线集成、质量验证和可见发布实现闭环。
CI/CD 流程中实现文档自动生成与更新，核心在于把文档当作“一等公民”——和代码一样受版本控制、随提交触发、经构建验证、同环境发布。不靠人工提醒，而靠配置驱动；不追求一次写全，而强调每次变更必同步。
选对工具，匹配技术栈
不同语言和架构有成熟适配的文档工具，强行统一反而增加维护成本：
- PHP 项目：优先用 phpDocumentor（提取 PHPDoc 注释生成 API 文档）或 Scribe（轻量、静态 HTML、支持响应示例推断）；L5-Swagger 更适合已有 OpenAPI 生态的团队
- Java/Spring：Springfox 或现代替代品 Springdoc OpenAPI，直接从注解生成标准 OpenAPI JSON/YAML，可对接 Postman、网关、SDK 工具链
- 数据库结构：用 SchemaSpy（支持 MySQL/PostgreSQL/Oracle 等），配合 JDBC 驱动生成带关系图的 HTML 报告，主外键可视化是关键价值点
- 通用 Markdown 文档：如 README、设计说明等，用 DocToc 自动维护目录层级，避免手动增删标题后 TOC 失效
- AI 增强型场景：如 brpc 或复杂框架文档，可引入 DeepWiki-Open，基于 RAG 技术分析源码 + 注释 + 提交历史，生成带上下文解释的交互式文档
嵌入流程，而非附加动作
文档更新不能是“发版前补一发”，必须成为 CI/CD 流水线中一个明确阶段：
- 在 GitHub Actions 中，将文档生成设为独立 job，触发条件限定为
push到main或pull_request目标为main，且只监听src/**、docs/**、swagger.json等关键路径 - GitLab CI 可复用官方镜像（如
phpdoc/phpdoc），用pages类型 job 直接部署到 GitLab Pages，输出路径设为public，自动获得可访问 URL - 对于 ShowDoc 这类中心化平台，CI 脚本应调用其
/api/import/auto接口上传 Swagger 文件，而非导出再人工导入；Webhook 配置需绑定到仓库 push 事件 - SchemaSpy 运行需确保 CI 环境预装 Java 17+ 和对应 JDBC 驱动，推荐用
-dp参数指定驱动路径，避免依赖系统 classpath
验证质量，不止于生成
生成文档只是起点，CI 阶段要加入检查逻辑，防止“有文档但不可信”：
- phpDocumentor 可开启
ValidateConfiguration和NormalizePaths流程，在构建时报出缺失 @param/@return 的方法 - brpc 类项目可用
markdownlint-cli检查文档格式一致性，用markdown-link-check扫描死链 - Swagger 导入 ShowDoc 前，先用
swagger-cli validate校验语法正确性，避免无效文件阻塞流程 - DocToc 更新后，建议加一步
git diff --quiet判断是否真有变更，无变化则跳过 PR 创建，减少噪音
发布即可见，闭环才成立
文档生成完若藏在制品包里或仅存于日志中，就失去了自动化意义：
- 静态文档（HTML/Markdown）优先部署到 Pages 类服务（GitHub Pages、GitLab Pages、Nginx 容器），URL 固定且可分享
- 数据库文档（SchemaSpy）建议输出到项目仓库的
docs/schema/目录，并启用 GitHub Pages，让https://org.github.io/repo/schema/成为团队默认入口 - API 文档若走 ShowDoc/DeepWiki，CI 脚本需确保导入成功后返回状态码 200，并记录文档版本号或 commit hash 到页面 footer，便于审计追溯
- 所有文档产物应列入
artifacts（GitHub Actions）或cache（GitLab CI），供后续 stage 或人工下载验证
