使用Swagger与OpenAPI可自动生成PHP项目API文档：先安装swagger-php和openapi依赖，配置PSR-4自动加载，编写合规注解，生成openapi.json，最后静态托管Swagger UI并正确接入JSON。
如果您正在维护一个PHP项目，但每次接口变更后都要手动更新API文档，则文档极易滞后甚至失效。以下是使用Swagger与OpenAPI规范自动生成并部署接口文档的可行路径：
一、安装zircote/swagger-php及openapi/openapi依赖
swagger-php v4+ 版本已将注解类拆离至独立包，仅安装主库无法识别@OAGet等注释，必须同步引入OpenAPI核心类型定义。
1、执行命令安装主解析器：composer require zircote/swagger-php
2、执行命令安装注解类型支撑包：composer require openapi/openapi
立即学习“PHP免费学习笔记（深入）”；
3、验证vendor/zircote/swagger-php/src/Annotation.php和vendor/openapi/openapi/src/Annotations/Get.php均存在
二、配置PSR-4自动加载并确保控制器可被扫描
swagger-php仅扫描被Composer自动加载器覆盖的PHP文件，若控制器位于未注册路径（如app/Http/Controllers但未在composer.json中声明），则注释将被完全忽略。
1、打开composer.json，在autoload段添加PSR-4映射："App\": "app/"
2、确认控制器文件路径与命名空间一致，例如AppHttpControllersUserController对应文件为app/Http/Controllers/UserController.php
3、运行composer dump-autoload刷新自动加载映射
三、在控制器方法上方编写合规OpenAPI注解
注释必须严格遵循OpenAPI v3语法，且须紧贴方法声明行，中间不得插入空行；任何格式偏差都将导致该接口不被收录。
1、在控制器类顶部或方法上方添加命名空间引用：use OpenApiAnnotations as OA;
2、在public function index(Request $request)上方紧邻位置添加注释块：/** @OAGet(path="/api/users", summary="获取用户列表", @OAResponse(response="200", description="OK") ) */
3、路径参数需显式声明：@OAParameter(name="id", in="path", required=true, @OASchema(type="integer"))
4、请求体必须指定content与MIME类型：@OARequestBody(content=@OAJsonContent(@OAProperty(property="name", type="string")))
四、生成openapi.json并校验结构完整性
生成命令需指向实际包含注解的PHP文件目录，输出路径应设为Web可访问位置；若JSON中缺失paths字段或openapi版本号，说明扫描失败或注释非法。
1、执行扫描命令：./vendor/bin/openapi --output public/docs/openapi.json app/Http/Controllers/
2、检查生成文件首部是否含"openapi": "3.0.3"字段
3、搜索文件中是否存在"paths"节点及其子项，确认至少有一个接口路径被收录
4、若无内容，临时在控制器类顶部添加/** @OAInfo(title="API", version="1.0") */测试基础扫描能力
五、静态托管Swagger UI并配置JSON接入
Swagger UI必须通过HTTP服务加载openapi.json，直接双击index.html将因CORS策略导致空白页面；其url字段需指向相对于UI根目录的正确JSON路径。
1、下载Swagger UI最新版，解压至public/docs/目录
2、编辑public/docs/index.html，定位到url字段，修改为：url: "/docs/openapi.json"
3、确保Web服务器能访问/public/docs/openapi.json，可通过浏览器直接请求该URL验证返回JSON是否可读
4、启动PHP内置服务器：php -S localhost:8000 -t public，然后访问http://localhost:8000/docs/
