Composer不生成文档，需依赖phpdocumentor等工具；v3配置易错三点：fileset包裹directory、output设为docs/api、exclude显式排除Tests等目录。
Composer 本身不生成文档，所有“自动化生成 API 文档”都依赖外部工具（如 phpdocumentor/phpdocumentor、zircote/swagger-php 或 sami/sami）+ 显式配置 scripts。没装对工具、路径写错、注释不规范，跑出来的就是空目录或报错页面。
phpdocumentor v3 配置文件里三处最容易写错
很多人复制模板后生成失败，问题基本出在这三个地方：
-
<directory>标签在 v3 已废弃，必须用<fileset>包裹，且路径是相对于phpdoc.xml所在位置，不是项目根目录 —— 比如phpdoc.xml在项目根目录，<directory>src</directory>就得改成<directory>./src</directory> -
<output>建议固定为docs/api，CI 部署时 GitHub Pages 默认托管这个路径；写成./build/docs可能导致 CI 脚本找不到输出 - 漏掉
<exclude>会导致扫描Tests、Fixtures目录，不仅拖慢速度，还会把测试类塞进文档索引 —— 正确写法：<exclude>src/Tests</exclude>
swagger-php 注解不生效的典型原因
写了 @OAGet 却没出现在 openapi.yaml 里？先检查这几点：
Discussion Composer
下载
围绕关键发现、作用机制、临床相关性及研究局限性展开讨论。适用于撰写或优化任何生物医学论文的“讨论（Discussion）”部分——包括结果解读、与既往文献关联、阐释意外发现、界定研究局限性，以及撰写结论。当用户输入以下任一指令时也会自动触发该功能： - “write my discussion” - “help me discuss my findings” - “how do I compare to prior studies” - “write the limitations par
- 顶层
@OAInfo缺失：必须有一个全局@OAInfo注解（哪怕只写@OAInfo(title="API", version="1.0")），否则生成的 YAML 不合法，Swagger UI 直接报 “no info.title” - 扫描路径错误：
OpenApiscan(['src'])中的'src'必须是真实存在的目录，且该目录下至少有一个含@OA*注解的 PHP 文件；如果用了命名空间但没被 Composer autoloader 加载，scan()就读不到 -
vendor/bin/openapi找不到：不是安装失败，而是 Composer 没软链脚本 —— 改用php vendor/zircote/swagger-php/bin/openapi直接调用更稳
composer.json scripts 中多步骤命令怎么写才可靠
单条字符串容易出错，尤其涉及清理、内存限制、顺序执行时：
- 用数组代替字符串：比如
"docs": ["rm -rf docs/api", "php -d memory_limit=-1 vendor/bin/phpdoc --config=phpdoc.xml"]，保证前一步成功再执行下一步 - Windows 用户慎用
rm -rf：改用PowerShell -Command "Remove-Item -Recurse -Force docs\api"或跨平台工具如robloach/component-installer - 避免硬编码路径：
vendor/bin/phpdoc在某些 CI 环境可能不存在，推荐写全路径php vendor/bin/phpdoc（PHP 解析器显式调用更兼容）
生成的文档部署到 GitHub Pages 的关键路径
CI 构建完文档后，GitHub Pages 能直接访问的前提很具体：
- 输出目录必须是
docs/api（不是public/docs或build/docs），且docs/是 Git 仓库的子目录 - GitHub Pages 设置里选 “Deploy from a folder”，填
/docs（注意开头斜杠），不是docs/api - 如果想用自定义域名，
docs/CNAME文件必须存在且内容为域名（无协议、无路径），且 DNS A 记录指向 GitHub Pages IP
真正麻烦的不是第一次跑通，而是后续每次提交后文档是否自动更新、是否和代码保持同步、排除规则有没有随新目录结构追加 —— 这些细节不持续维护，生成的文档很快就会变成误导源。
