如何通过Composer脚本自动生成文档或API蓝图？（自动化工作流）

composer 脚本本身不直接生成文档，但可通过配置 scripts 字段调用 swagger-php、phpDocumentor 等工具自动生成 API 文档和代码文档，并支持转为 API Blueprint 格式，还可集成到 pre-commit、CI/CD 及版本钩子中实现自动化。

Composer 脚本本身不直接生成文档或 API 蓝图，但它可以作为自动化工作流的“触发器”和“粘合层”，调用专用工具完成生成任务。关键在于把文档生成逻辑封装成可执行命令（如 PHP 脚本、CLI 工具），再通过 composer.json 的 scripts 字段注册为 Composer 命令。

配置 Composer 脚本调用文档生成工具

在 composer.json 中定义脚本，例如使用 swagger-php 生成 OpenAPI（兼容 API Blueprint 格式）或用 phpDocumentor 生成代码文档：

• 确保已安装工具：运行 composer require --dev zircote/swagger-php phpdocumentor/phpdocumentor
• 在 composer.json 的 "scripts" 下添加：

"scripts": {   "docs:api": "php -r "require 'vendor/autoload.php'; (new \OpenApi\Generator())->generate(['src'], 'docs/openapi.yaml');"",   "docs:phpdoc": "phpdoc -d src -t docs/api",   "docs:build": [     "@docs:api",     "@docs:phpdoc"   ] }

之后执行 composer run docs:build 即可一键生成两类文档。

将 API 注释转为 API Blueprint（.apib）格式

原生 swagger-php 输出 OpenAPI（YAML/JSON），若需 API Blueprint，可用转换工具桥接：

• 安装 apiaryio/api-blueprint-cli 或使用在线/本地转换器（如 apib2openapi 的反向工具）
• 更推荐：用 swagger2apib（node.js 工具）——先生成 OpenAPI，再转 .apib：

"scripts": {   "docs:apib": "php artisan swagger:generate && swagger2apib docs/openapi.yaml > docs/api.apib" }

注意：需提前全局安装 npm install -g swagger2apib，并确保 swagger:generate 是你项目中已有的 Artisan 命令（laravel）或自定义 PHP 脚本。

集成到开发与发布流程

让文档生成成为日常习惯，而非手动补救：

• 提交前校验：在 pre-commit 钩子中运行 composer run docs:build，失败则阻止提交（配合 GrumPHP 更可靠）
• CI/CD 自动化：gitHub Actions 或 gitlab CI 中加入步骤，生成文档后推送到 gh-pages 分支或上传至文档站点
• 版本绑定：在 post-update-cmd 或 post-install-cmd 中触发生成，确保文档与当前依赖/代码状态一致

小技巧：用 PHP 脚本封装复杂逻辑

当命令行链过长或需条件判断时，写一个简单的 PHP 文件更清晰：

• 新建 scripts/generate-docs.php，读取配置、检查注释覆盖率、调用生成器、验证输出格式
• 在 composer.json 中注册："docs:gen": "php scripts/generate-docs.php"
• 支持参数传递：如 composer run docs:gen -- --format=apib --output=dist/（需在脚本中解析 $argv）

基本上就这些。核心不是 Composer 多强大，而是它帮你把「写注释 → 运行命令 → 输出文档」这个链条稳稳串起来，省去重复操作和遗漏风险。