Lumen8使用SwaggerLume时如何将Swagger注解迁移至独立YAML文件

SwaggerLume底层依赖zircote/swagger-php包，本身就支持外部YAML文件加载，不需要在业务代码里写大量冗余注解，有三种可直接落地的方案，改造成本从低到高如下：

方案1：利用原生$ref引用外部YAML（改造成本最低） #

不需要修改扩展包核心逻辑，只需要保留极少量基础注解，其余内容全拆分到YAML：

• 先创建专门的Swagger资源目录，比如resources/swagger/，可以按业务模块拆分文件：比如schemas.yaml存所有数据结构、user.yaml存用户模块接口、order.yaml存订单模块接口。
• 只需要在全局基类（比如app/Http/Controllers/Controller.php）的类注释上写最基础的OpenAPI头部配置，其余内容通过ref引用外部YAML即可，示例：

/**
 * @OA\OpenApi(
 *   @OA\Info(version="1.0.0", title="项目API文档", description="REST API 接口文档"),
 *   @OA\Server(url=L5_SWAGGER_CONST_HOST, description="服务访问地址")
 * )
 * @OA\PathItem(ref="#/resources/swagger/user.yaml")
 * @OA\PathItem(ref="#/resources/swagger/order.yaml")
 * @OA\Schema(ref="#/resources/swagger/schemas.yaml")
 */

• YAML文件内直接按OpenAPI 3.0规范写内容即可，比如user.yaml里直接写接口路径、请求响应规则，生成文档时swagger-php会自动解析合并引用内容。
• 确认config/swagger-lume.php中scanOptions的ExternalRef处理器处于开启状态，默认就是开启状态，不需要额外修改。

方案2：将YAML目录加入扫描路径（零业务注解侵入） #

SwaggerLume依赖的高版本swagger-php本身支持直接扫描YAML/JSON格式的文档文件，不需要写任何PHP注解：

• 先执行php artisan swagger-lume:publish发布扩展配置文件。
• 打开config/swagger-lume.php，找到scanPaths配置项，把你存放YAML文件的目录加入扫描列表，示例配置：

'scanPaths' => [
    app_path('Http/Controllers'), // 原有控制器扫描路径，不需要保留注解可以直接删掉
    resource_path('swagger'), // 新增YAML文件存放目录
],

• 把所有接口定义、Schema、安全配置全写在resources/swagger目录下的YAML文件里，结构完全遵循OpenAPI 3.0规范即可，执行php artisan swagger-lume:generate时会自动扫描该目录下的YAML文件，和PHP注解的内容合并生成最终文档。如果不想在业务代码里留任何Swagger注解，直接把控制器路径从scanPaths里删掉就行。

方案3：完全接管文档生成逻辑（全YAML管控） #

如果不想依赖扩展的扫描逻辑，想完全用YAML管理所有文档内容，可以自定义生成逻辑：

• 把所有文档内容按OpenAPI规范写在YAML文件中，主入口文件比如resources/swagger/openapi.yaml，其他模块文件通过$ref在主文件中引用。
• 重写SwaggerLume的文档生成方法：可以自定义一个artisan命令，读取主YAML文件内容，用YAML解析组件转成数组，校验格式后直接生成json文件存到public/docs目录下，替换掉扩展默认生成的文档即可。
• 这个方案完全脱离PHP注解，业务代码里没有任何Swagger相关内容，后续维护只需要改YAML文件即可。

注意事项 #

• 所有YAML内容必须严格符合OpenAPI 3.0规范，建议用编辑器的OpenAPI校验插件提前排查语法错误，避免生成文档时报错。
• 引用外部文件时注意相对路径写法：同文件内引用用#/components/schemas/xxx格式，跨文件引用写对文件相对路径，后面拼接#加文件内节点路径即可。
• 拆分文件建议按职责划分：公共请求头、通用响应码单独放公共配置文件，业务接口按模块拆分，数据结构单独存Schema文件，后期维护成本远低于写在PHP注解里。

内容的提问来源于stack exchange，提问作者DJeong