Composer 通过 scripts 字段调用 swagger-php 生成 OpenAPI YAML：先安装 zircote/swagger-php，再在 composer.json 中配置 "docs:api": "php -r "require 'vendor/autoload.php'; (new OpenApiGenerator())->generate(['src'], 'docs/openapi.yaml');""，确保 src 目录含注解且 docs/ 可写。
Composer 本身不生成接口规范，但能可靠地触发 swagger-php、zircote/swagger-php 或 openapi-generator 等工具完成生成任务。关键在于把生成逻辑封装成可执行命令，并通过 composer.json 的 scripts 字段注册为标准命令。
怎么配置 scripts 调用 swagger-php 生成 OpenAPI YAML
swagger-php 是 PHP 生态最主流的注解式 OpenAPI 生成器，它读取代码中的 @OAGet、@OAPost 等注解，输出 openapi.yaml 或 openapi.json。它不依赖运行时，纯静态分析，适合 CI/CD 集成。
- 先安装：运行
composer require --dev zircote/swagger-php - 确保控制器或 API 类里写了标准 OpenAPI 注解（比如
@OAInfo、@OAPathItem） - 在
composer.json的scripts中添加：
"docs:api": "php -r "require 'vendor/autoload.php'; (new \OpenApi\Generator())->generate(['src'], 'docs/openapi.yaml');""
注意：src 是你的 API 类所在目录；docs/openapi.yaml 必须是可写路径，且 docs/ 目录需提前存在（否则会报错）。
为什么 post-autoload-dump 不适合生成接口文档
post-autoload-dump 在 vendor/autoload.php 生成后触发，但它只保证类加载映射就绪，并不保证注解解析环境完整——swagger-php 不依赖 autoloader 加载类，而是用反射 + 文件扫描，反而可能因类未实际 require 而漏掉注解。
- 更稳妥的做法是显式调用命令，如
composer run docs:api - 若想自动化，应绑定到
post-update-cmd或post-install-cmd，这两个事件在依赖就位、代码树稳定后才执行 - 避免在
pre-autoload-dump中做这事：此时vendor/可能还没完全解压，autoload.php也未生成，require 'vendor/autoload.php'会直接失败
怎么把 OpenAPI 转成 API Blueprint（.apib）格式
API Blueprint 是另一种轻量级 API 描述格式，部分网关（如 Apiary）或测试工具（如 Dredd）原生支持它，但 swagger-php 默认不输出 .apib。
- 可用开源转换器桥接，例如
api-spec-converter（Node.js 工具）：
npx api-spec-converter --from=openapi_3 --to=api_blueprint docs/openapi.yaml > docs/api.apib
- 把它加进 Composer 脚本链中，比如：
"docs:apib": "npx api-spec-converter --from=openapi_3 --to=api_blueprint docs/openapi.yaml > docs/api.apib", "docs:build": ["@docs:api", "@docs:apib"]
注意：npx 要求部署机已装 Node.js；若在纯 PHP 环境（如某些容器），建议改用 PHP 实现的转换器（如 openapi-to-apib），或直接在 CI 步骤中分阶段处理，别强塞进 Composer 脚本。
容易被忽略的权限和路径问题
本地跑通不代表上线能用。常见断点不在逻辑，而在路径和权限：
-
docs/目录必须存在且 webserver 用户有写权限，否则generate()会静默失败（不抛异常，只返回空内容） - 使用相对路径（如
'src'）时，php -r执行上下文是项目根目录，但某些 CI 环境会切换工作目录，建议统一用__DIR__ . '/src'显式指定 - 若用 Laravel，别直接在
app/Http/Controllers写注解——Laravel 的自动发现机制可能导致路由未注册时注解不可见；优先放在独立的src/Api/下并确保 PSR-4 映射正确 - 生成的
openapi.yaml建议加入.gitignore，它属于构建产物；但docs/目录下可保留index.html（用 Swagger UI 渲染）供人工查阅
真正卡住人的往往不是工具选型，而是生成路径是否可写、注解是否被扫描到、以及 CI 环境里 Node.js 或 PHP 版本是否兼容转换步骤。
