如何在Laravel的darkaonline/l5-swagger生成的Swagger JSON中添加"swagger": "2.0"

我来帮你解决这个问题——要在darkaonline/l5-swagger生成的Swagger JSON里同时保留openapi: "3.0.0"和新增swagger: "2.0"字段，有两种可行方案，分别适配临时需求和长期自动生成的场景：

方案一：手动修改生成后的JSON文件（临时快速解决） #

如果只是临时需要这个字段，直接修改已生成的JSON文件即可：

• 找到包默认生成的JSON文件，路径一般是storage/api-docs/api-docs.json
• 打开文件，在最外层的JSON对象中直接添加"swagger": "2.0"字段，比如：

{
  "openapi": "3.0.0",
  "swagger": "2.0",
  "info": {
    "title": "Ubi Api",
    "description": "Ubi Api Documenation",
    "contact": { "email": "admin@abc.com" },
    "license": { "name": "Apache 2.0", "url": "http://www.apache.org/licenses/LICENSE-2.0.html" },
    "version": "0.0.1"
  },
  // ... 其他内容
}

不过要注意：每次运行php artisan l5-swagger:generate重新生成文档时，这个手动修改的字段会被覆盖，所以如果需要长期生效，建议用下面的方案。

方案二：自定义生成逻辑自动添加字段（长期持久方案） #

通过扩展包的生成器类，让每次生成文档时自动注入swagger: "2.0"字段：

步骤1：创建自定义生成器类 #

在你的Laravel项目中创建一个自定义服务类，继承原包的生成器：

<?php

namespace App\Services;

use Darkaonline\L5Swagger\Generator;

class CustomSwaggerGenerator extends Generator
{
    /**
     * 重写生成文档的方法，添加swagger字段
     * @return array
     */
    public function generateDocs(): array
    {
        // 调用父类方法生成原始的OpenAPI 3.0文档数组
        $originalDocs = parent::generateDocs();
        
        // 手动添加swagger字段
        $originalDocs['swagger'] = '2.0';
        
        return $originalDocs;
    }
}

步骤2：替换原生成器的绑定 #

打开app/Providers/AppServiceProvider.php，在register方法中添加绑定，让Laravel使用我们的自定义生成器：

public function register()
{
    // 替换L5Swagger的默认生成器为自定义类
    $this->app->bind(
        \Darkaonline\L5Swagger\Generator::class,
        \App\Services\CustomSwaggerGenerator::class
    );
}

步骤3：重新生成文档 #

运行Artisan命令重新生成Swagger文档，之后生成的JSON就会自动包含swagger: "2.0"字段了：

php artisan l5-swagger:generate

注意事项 #

需要提醒的是：openapi字段对应OpenAPI 3.x规范，swagger字段对应Swagger 2.0（也就是OpenAPI 2.0）规范，同时存在这两个字段可能会让部分Swagger工具产生解析混淆。建议你先确认自己的使用场景确实需要同时保留这两个字段，再进行以上修改。

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