PHP API文档生成需匹配项目阶段、团队协作与CI/CD流程：主流方案是用zircote/swagger-php在代码中添加@OA\Get等注解生成OpenAPI规范，再通过Swagger UI渲染为交互式文档；Laravel项目应优先选用l5-swagger封装方案，避免手动配置；phpDocumentor适用于仅需PHPDoc技术参考的场景；关键是要将注解作为唯一信源，JSON文档由CI自动生成并动态注入环境配置，确保代码与文档强同步。
PHP API文档生成不是“选个工具点一下就完事”，而是要根据项目阶段、团队协作方式和发布流程，决定用注释驱动还是路由驱动、是否需要交互式测试界面、以及文档是否随CI/CD自动更新。不匹配的方案会导致注释没人写、生成失败、或上线后文档立刻过期。
用 zircote/swagger-php 在代码里写注解生成 OpenAPI
这是目前最主流的 PHP 文档生成路径，尤其适合 Laravel、Symfony 等框架。核心逻辑是：在控制器方法上加 @OA\Get、@OA\Post 这类注解，运行命令生成 openapi.json，再喂给 Swagger UI。
常见错误现象：
- 生成的 JSON 文件为空或只含
info字段 → 没加use OpenApi\Annotations as OA;或命名空间引用错 -
vendor/bin/openapi报 “Class not found” → 没执行composer install或 autoloader 损坏 - 参数没出现在文档里 → 忘了加
@OA\Parameter，或用了@param（那是给 phpDocumentor 的，swagger-php 不认）
实操建议：
立即学习“PHP免费学习笔记（深入）”；
- 注解必须写在方法内部或紧邻方法的 DocBlock 里，不能只写在类上
- 路径变量如
/users/{id}要配@OA\Parameter(name="id", in="path")，否则 swagger-ui 无法填充 - 响应体模型用
@OA\Schema(ref="#/components/schemas/User")+ 单独定义@OA\Schema(schema="User", ...)，避免内联结构导致重复 - 生成命令建议加
--output public/openapi.json --format json，明确输出路径和格式
用 phpdocumentor/phpdocumentor 解析 PHPDoc 注释
它不关心 HTTP 路由，只解析 @param、@return、@throws 这类标准标签，适合生成面向开发者的技术参考文档，比如 SDK、Lib 库、或框架内部 API 手册。
使用场景：
- CodeIgniter、ThinkPHP 等轻量框架没有统一路由注解机制，但已有大量 PHPDoc，可直接复用
- 想生成带类图、继承链、方法调用关系的深度文档
- 需要 PDF/CHM 等离线格式（
phpdocumentor支持）
容易踩的坑：
-
phpdoc run默认只扫src/，若控制器在app/Http/Controllers就会漏掉 → 必须用-d app显式指定目录 - 注释里混用中文标点（如“：”、“（”）会导致解析中断 → 全部改用英文冒号、半角括号
- 没写
@package标签时，生成的 HTML 目录结构混乱 → 建议每个类加@package Api\Controllers
Laravel 项目优先用 l5-swagger 而非裸装 swagger-php
l5-swagger 是对 zircote/swagger-php 的 Laravel 封装，省去手动配置路径、JSON 输出位置、UI 静态资源托管等琐事。但它不是“零配置”——很多失败源于误以为它能自动扫描所有路由。
关键差异点：
-
l5-swagger:generate只处理加了@OA\注解的文件，不会自动读取routes/api.php里的Route::get() - 默认配置下，Swagger UI 页面访问路径是
/api/documentation，但该页面依赖public/docs/index.html和public/docs/swagger.json，两者缺一不可 - 开发环境开启
APP_DEBUG=true才能显示 UI；生产环境需手动复制public/vendor/swagger-ui到public/docs
实操建议：
立即学习“PHP免费学习笔记（深入）”；
- 先运行
php artisan vendor:publish --provider="L5Swagger\L5SwaggerServiceProvider"再改config/l5-swagger.php，别跳过这步 - 在
config/l5-swagger.php的'paths' => ['docs' => 'public/docs']要和php artisan l5-swagger:generate实际输出路径一致 - CI 流程中加
php artisan l5-swagger:generate --force，避免因缓存导致文档未更新
文档生成后怎么真正管起来
生成一次文档只是开始。真正的维护难点在于同步性与可见性：谁改了接口，文档是否跟着改？前端是否知道最新字段？错误码变更有没有通知到测试同学？
复杂点或容易被忽略的地方：
- Swagger JSON 文件不能直接放 Git 里当“源”——它应是构建产物。应把注解留在代码里，JSON 由 CI 自动生成并部署到静态服务器
- 多个环境（dev/staging/prod）共用一份文档时，
host和servers字段必须动态注入，硬编码会导致前端调试连错地址 - YAML 格式虽易读，但 PHP 工具链普遍更稳支持 JSON 输出；若坚持用 YAML，注意缩进必须用空格，且
vendor/bin/openapi默认不生成 .yaml - 文档里写的
@OA\Example很少被前端真正用上——不如在响应示例里塞真实业务数据（如用户头像 URL、时间戳格式），比 “string” 有用得多
