答案：通过集成phpDocumentor或Sami到Composer的scripts中，可自动化生成API文档，提升项目可维护性；首先以dev依赖安装工具，再创建配置文件定义源码与输出路径，接着在composer.json中添加对应脚本命令，如"docs": "phpdoc"或"docs:sami": "sami.php update sami.conf.php"，最后通过composer run docs执行，还可结合CI/CD实现提交即构建，并将生成的静态文档部署至GitHub Pages等平台。
为你的Composer库生成API文档，能极大提升项目的可维护性和开发者体验。通过集成phpDocumentor或Sami到Composer的scripts中，你可以将文档生成变成自动化流程的一部分，比如在开发、测试或部署阶段一键执行。下面介绍如何配置这两种工具并将其融入Composer工作流。
使用phpDocumentor生成API文档
phpDocumentor是PHP社区广泛使用的文档生成工具，支持基于DocBlock注释自动生成结构清晰的HTML文档。
安装phpDocumentor
推荐以本地依赖方式安装，避免全局依赖带来的版本冲突：
立即学习“PHP免费学习笔记（深入）”；
// 在项目根目录执行- composer require --dev phpdocumentor/phpdocumentor
你也可以使用Phar文件，但通过Composer管理更便于团队协作。
创建配置文件
在项目根目录添加phpdoc.dist.xml：
<phpdocumentor>
<project name="My Library" version="1.0">
<directory source-path="./src">src/</directory>
<output target="./docs/api"/>
</project>
</phpdocumentor>
这个配置告诉phpDocumentor扫描src/目录，并输出文档到docs/api。
集成到Composer scripts
修改composer.json：
"docs": "phpdoc"
}
之后运行：composer run docs 即可生成文档。
使用Sami生成现代化API文档
Sami是另一个强大且灵活的API文档生成器，支持Git版本追踪和主题定制，适合长期维护的库。
安装Sami
- composer require --dev sami/sami
创建Sami配置文件
在项目根目录创建sami.conf.php：
__DIR__ . "/src",
array(
'title' => 'My Library API',
'build_dir' => __DIR__ . "/docs/api",
'cache_dir' => __DIR__ . "/var/cache/sami",
'default_opened_level' => 2,
)
);
这个配置指定源码路径、输出目录和缓存位置。
添加Composer脚本
更新composer.json：
"docs:sami": "sami.php update sami.conf.php"
}
注意：Sami提供的是sami.php脚本，需确保可执行。如果命令找不到，可以写完整路径：vendor/bin/sami.php update sami.conf.php
运行：composer run docs:sami 生成文档。
统一文档命令与自动化建议
你可以定义一个通用命令，方便团队使用：
"scripts": {"docs": "@php -r "echo 'Running API docs...\n';" && composer run docs:internal",
"docs:internal": "phpdoc"
}
若使用Sami，则将docs:internal改为sami.php update sami.conf.php。
进一步，可在.gitlab-ci.yml或GitHub Actions中加入文档构建步骤，确保每次提交后文档同步更新。
生成的静态文档可部署到GitHub Pages或Vercel等平台，对外公开访问。
基本上就这些。选择phpDocumentor还是Sami，取决于你对功能和外观的需求。phpDocumentor开箱即用，Sami更灵活但配置稍复杂。无论哪种，集成进Composer scripts都能让文档维护变得更简单。
