ubuntu composer如何生成文档

Ubuntu 下用 Composer 生成文档的实用方案

一 准备环境

• 确保已安装 PHP 与 Composer，并可用命令检查版本：
  • php -v
  • composer -v
• 建议将全局 Composer 的可执行目录加入 PATH，便于直接使用全局安装的工具（如 phpDocumentor、phpDox 等）。全局包通常位于 ~/.config/composer/vendor/bin（或旧版 ~/.composer/vendor/bin）。

二 常用工具与快速上手

• 生成 API 文档（HTML 站点）

  • 工具：phpDocumentor
  • 安装（项目内）：composer require --dev phpdocumentor/phpdocumentor
  • 生成：vendor/bin/phpdoc -d src -t docs
  • 安装（全局）：composer global require phpdocumentor/phpdocumentor
  • 生成（全局）：phpdoc -d src -t docs
  • 说明：扫描 src 目录的 PHPDoc 注释，输出静态 HTML 到 docs。适合对外 API 与库文档。

• 生成 Markdown 文档（轻量、易版本化）

  • 工具：klitsche/dog
  • 安装：composer require --dev klitsche/dog
  • 配置：在项目根目录创建 .dog.yml，示例：
    • title: ‘My API’
    • srcPaths:
      • ‘src’
  • 生成：vendor/bin/dog
  • 说明：基于 PHPDoc 注释生成 Markdown，便于放入仓库与持续集成。

• 生成 OpenAPI/Swagger 规范并配合 Swagger UI 预览

  • 工具：zircote/swagger-php（生成 swagger.json）
  • 安装：composer require --dev zircote/swagger-php
  • 生成：php vendor/zircote/swagger-php/bin/swagger src -o public/swagger/swagger.json
  • 预览：下载 Swagger UI 到 public/swagger-ui，将页面中的 swagger.json URL 指向生成的文件，浏览器访问即可在线调试。
  • 说明：适合需要在线调试、与前端/客户端协作的 RESTful API。

• Laravel 项目自动化生成（测试驱动）

  • 工具：owowagency/automated-api-docs
  • 安装：composer require owowagency/automated-api-docs
  • 发布配置：php artisan vendor:publish --provider=“OwowAgency\AutomatedApiDocs\ServiceProvider” --tag=“config”
  • 使用：在测试用例基类中引入 DocsGenerator，在测试里用 monitor() 标记需要记录的请求，测试结束自动导出 JSON 文档；可在部署脚本中加入任务（如 envoy run documentation）实现 CI/CD 自动生成。

三 在 PhpStorm 中集成与一键生成

• 安装文档工具（全局或项目内均可），例如：
  • composer global require phpdocumentor/phpdocumentor
• 在 PhpStorm 配置外部工具：
  • File > Settings > Tools > External Tools > 新建
  • Name：phpDocumentor
  • Program：phpdoc（全局）或 $ProjectFileDir$/vendor/bin/phpdoc（项目内）
  • Parameters：-d $ProjectFileDir$/src -t $ProjectFileDir$/docs
  • Working directory：$ProjectFileDir$
• 之后可通过右键菜单或工具栏按钮一键生成，并在 docs/index.html 查看结果。

四 实用建议

• 统一规范：为控制器、模型、DTO、异常等编写符合 PHPDoc 标准的注释，减少后期维护成本。
• 输出与发布：将生成的 docs/、swagger/ 目录加入版本控制或接入 CI，保证文档与代码同步发布。
• 选择工具：需要“可浏览的站点”选 phpDocumentor；需要“轻量可读”选 klitsche/dog；需要“在线调试”选 swagger-php + Swagger UI；若是 Laravel，可用 owowagency/automated-api-docs 做自动化。