PHP API文档自动生成需装swagger-php与openapi两组件，注解须严格遵循OpenAPI v3规范，路径、参数、响应缺一不可，并配置自动加载与扫描路径，最后用Swagger UI展示。
PHP平台API文档能自动生成，核心是用代码注解代替手写文档，靠工具扫描注解、输出标准OpenAPI（Swagger）格式文件，再用UI渲染成可交互页面。整个过程不依赖人工同步，改接口时只要更新注解，重新生成就能拿到最新文档。
装对工具链：swagger-php + openapi
只装 Swagger UI 不行，它只是“看文档”的前端；真正干活的是 PHP 侧的解析器。
- 运行
composer require zircote/swagger-php安装主解析器 - 必须额外加装
composer require openapi/openapi，否则@OAGet等注解无法识别（v4+ 版本已拆分） - 验证
vendor/zircote/swagger-php/src/Annotation.php和vendor/openapi/openapi/src/Annotations/Get.php都存在
注解要写得准：路径、参数、响应一个不能少
注解不是随便加在方法上面就行，格式和语义必须严格匹配 OpenAPI v3 规范。
- 注释块必须紧贴方法声明，中间不能有空行
-
path值要和真实路由完全一致，比如框架路由是/api/v1/users，就写@OAGet(path="/api/v1/users")，不能省略前缀 - 查询参数（如
?page=1&limit=10）必须用@OAParameter(in="query")显式声明，不会从函数参数自动推导 - 请求体（JSON）要用
@OARequestBody包裹@OAJsonContent，再逐个定义@OAProperty - 别忘了加
@OAInfo和@OAServer，否则 Swagger UI 不知道往哪发测试请求
让工具扫得到：路径、命名空间、自动加载都得配好
如果生成的 openapi.json 里 paths 是空的，大概率是扫描范围没覆盖到控制器文件。
立即学习“PHP免费学习笔记（深入）”；
- 检查
composer.json的autoload段是否注册了控制器所在目录，例如："App\": "app/" - 确保控制器类名与命名空间、文件路径一致（如
AppHttpControllersUserController对应app/Http/Controllers/UserController.php） - 执行
composer dump-autoload刷新映射 - 生成命令要指向实际含注解的目录，例如：
./vendor/bin/openapi app/ --out public/openapi.json
部署成可访问的交互页面
有了 openapi.json，下一步是把它“展示出来”。
- 把 Swagger UI 的
dist目录放进 Web 根目录（如public/swagger-ui） - 修改
index.html中的url指向你的 JSON 文件，例如：url: "/openapi.json" - 确保该 JSON 路径可通过 HTTP 正常访问（无 403、跨域或重写拦截）
- Laravel 用户推荐直接用
darkaonline/l5-swagger，它把生成、托管、路由全封装好了，执行php artisan l5-swagger:generate后访问/api/documentation即可
