PHPDocumentor v3配置三处硬伤：①废弃<directory>标签，须用<fileset><directory>./src</directory></fileset>；②<o>output>应固定为docs/api；③<o>exclude>需显式排除Tests等非生产目录。
phpdocumentor v3 配置文件三处硬伤
phpdoc.xml 写错，php vendor/bin/phpdoc 就跑不出文档——不是工具没装，而是配置本身不合法。v3 版本废弃了 <directory> 标签，但很多人直接从 v2 模板复制过来，导致扫描路径失效。
-
<fileset>必须包裹所有路径定义，<directory>单独出现会静默忽略；正确写法是<fileset><directory>./src</directory></fileset>（注意./前缀，路径相对于phpdoc.xml所在位置） -
<output>建议固定为docs/api，GitHub Pages 默认托管该路径；写成./build/docs或build/docs会导致 CI 构建后找不到可部署目录 -
<exclude>必须显式列出src/Tests、src/Fixtures等非生产代码目录，否则 phpDocumentor 会把测试类方法塞进索引，生成冗余页面且拖慢速度
swagger-php 注解不生效的排查顺序
@OAGet 写了却不出现在 openapi.yaml 里？别急着重写注释，先确认这三点是否成立：
- 项目根目录下必须有且仅有一个顶层
@OAInfo注解（哪怕只写@OAInfo(title="API", version="1.0")），否则生成器拒绝输出合法 YAML，Swagger UI 直接报no info.title -
OpenApi::scan(['src'])中的'src'是真实存在的相对路径，且该目录下至少有一个 PHP 文件含@OA*注解；如果用了命名空间但未被 Composer autoloader 加载，scan()就读不到任何东西 -
vendor/bin/openapi在 Windows 或某些 CI 环境中可能软链失效，改用php vendor/zircote/swagger-php/bin/openapi调用更稳，避免 “command not found” 类错误
composer.json scripts 多步骤命令怎么写才不翻车
单行字符串拼接命令（如 "docs": "rm -rf docs/api && php vendor/bin/phpdoc --config=phpdoc.xml"）在 CI 中极易因前序失败而静默跳过后续步骤，或在 Windows 下直接报错。
- 用数组写法强制顺序执行：
"docs": ["rm -rf docs/api", "php -d memory_limit=-1 vendor/bin/phpdoc --config=phpdoc.xml"]，Composer 会逐条运行，上一条失败则中断 - Windows 用户避开
rm -rf，改用 PowerShell 命令：PowerShell -Command "Remove-Item -Recurse -Force docs\api"，或统一用跨平台工具（如robloach/component-installer提供的清理脚本） - 避免硬编码
vendor/bin/phpdoc，CI 环境中该路径可能不存在；推荐写全路径php vendor/bin/phpdoc，显式调用 PHP 解析器，兼容性更高
静态 HTML 页面加载 OpenAPI 文档的最小可行方案
所谓“HTML 做 Swagger 页面”，本质是前端加载并渲染一个已存在的 openapi.json，不是生成它。你不需要构建工具、不需要 React，只要确保 JSON 可被浏览器读取。
立即学习“前端免费学习笔记（深入）”；
- 用
swagger-ui-dist最轻量：CDN 引入https://unpkg.com/swagger-ui-dist@5/swagger-ui-bundle.js和 CSS，然后new SwaggerUIBundle({ url: "/api/openapi.json" }) -
url必须可跨域获取；若本地用file://打开 HTML，浏览器会因 CORS 拒绝加载，必须起服务（npx serve或python -m http.server） - 不要引入
swagger-ui-react或redoc-cli—— 它们需要构建流程和 JSX 支持，纯静态页加了反而要配 Webpack、Babel，徒增复杂度
真正卡住人的往往不是工具选型，而是路径相对性、排除规则遗漏、以及跨平台命令兼容性这些细节。CI 脚本里多一个点、少一个斜杠，就足以让整个文档流水线空跑一整晚。
