在Yii 2.0.55中生成可交互Swagger文档需手动引入swagger-php 3.0.4和doctrine/annotations，配置OpenAPI根注释（含@OA\Info、@OA\Server、@OA\Swagger），为接口添加@OA注解或YAML定义，执行命令生成swagger.json，并集成Swagger UI实现在线调试。
在Yii 2.0.55项目中自动生成可交互的Swagger API文档，需绕过框架默认不支持注解解析的限制，手动引入swagger-php并配置命令行生成流程，确保文档与代码变更实时同步。
安装swagger-php与依赖
执行命令安装OpenAPI 3.0兼容的解析器：composer require zircote/swagger-php:3.0.4。
必须同时安装Doctrine注解库，否则@OA\*注解无法被识别：composer require doctrine/annotations。
【不装doctrine/annotations会导致所有注解被忽略，生成空json】
编写全局OpenAPI配置注释
在api/controllers/SwaggerController.php或独立文件api/web/swagger.php顶部添加完整OpenAPI根配置。
注释中必须包含@OA\Info、@OA\Server和@OA\Swagger三组核心结构，缺一不可。
host字段要填实际部署域名（如api.example.com），不能写localhost，否则Swagger UI加载后请求会跨域失败。
为每个接口添加@OA注解
方法一：直接在action方法上方写注释
在controllers/UserController.php的actionIndex()前插入：
/*** @OA\Get(* path="/v1/users",* summary="获取用户列表",* @OA\Response(response="200", description="成功")*/
方法二：集中写在单独文件
新建api/docs/openapi/user.yaml，用YAML格式定义接口，再通过swagger-php的--yaml参数加载。
注意：Yii路由规则（如'users' => 'user/index'）不会被自动映射，@OA\Get中的path必须是最终对外暴露的真实路径，不是控制器方法名。
生成swagger.json文件
第一步：确认注释文件位置
将所有含@OA\*注释的PHP文件放在api/controllers/和api/models/目录下。
第二步：执行生成命令php vendor/bin/openapi api/controllers/ api/models/ -o api/web/swagger-docs/swagger.json。
第三步：检查输出结果
打开生成的swagger.json，搜索"paths"字段，确认至少有一条接口路径存在；若为空，说明注释未被扫描到或语法错误。
第四步：验证JSON有效性
把文件拖入https://editor.swagger.io，红色报错即表示注解格式有误，常见问题是缺少@OA\Tag或@OA\Response嵌套层级错位。
集成Swagger UI界面
下载最新版Swagger UI压缩包，解压后重命名为swagger-ui，放入api/web/目录。
修改api/web/swagger-ui/dist/index.html中url字段，指向"/swagger-docs/swagger.json"。
访问http://your-domain/swagger-ui/dist/index.html，页面加载后应显示完整接口列表，点击任意接口可发起在线调试。
