如何修改Laravel的L5-Swagger UI，替换URL搜索栏为版本选择下拉框？

第一步：配置并生成多版本Swagger文档 #

1. 复制L5-Swagger基础配置文件，为每个API版本创建独立配置：

   cp config/l5-swagger.php config/l5-swagger-v1.php
   cp config/l5-swagger.php config/l5-swagger-v2.php
   

2. 修改每个版本的配置文件，重点调整核心参数：
   • 'api-docs' => 'docs/v1'（v2版本对应docs/v2，以此类推）
   • 'scanOptions'里的扫描路径，比如限定为app/Http/Controllers/Api/V1（确保只扫描对应版本的控制器）
   • 可选：调整'routes'下的api路径，实现各版本文档独立访问（如api/documentation/v1）
3. 分别生成各版本的Swagger JSON文件：

   php artisan l5-swagger:generate --config=l5-swagger-v1.php
   php artisan l5-swagger:generate --config=l5-swagger-v2.php
   

第二步：自定义Swagger UI视图 #

1. 发布L5-Swagger的视图文件到项目目录：

   php artisan vendor:publish --tag=l5-swagger-views
   

   发布后视图文件位于resources/views/vendor/l5-swagger/index.blade.php

2. 修改视图文件，替换默认URL搜索栏为版本下拉框：

   • 找到原URL搜索栏代码块（包含input_baseUrl的div），替换为以下内容：

     <div class="input-group mb-3">
         <label class="input-group-text" for="apiVersion">API版本</label>
         <select class="form-select" id="apiVersion">
             <option value="/docs/v1/swagger.json">v1</option>
             <option value="/docs/v2/swagger.json">v2</option>
             <option value="/docs/v3/swagger.json">v3</option>
         </select>
     </div>
     

   • 在页面底部的JavaScript代码块中，添加版本切换逻辑：

     // 初始化加载默认版本（示例为v1）
     window.ui = SwaggerUIBundle({
         url: '/docs/v1/swagger.json',
         // 保留原有的dom_id、deepLinking等其他配置
     });
     
     // 监听下拉框切换事件
     document.getElementById('apiVersion').addEventListener('change', function() {
         window.ui.specActions.updateSpec({url: this.value});
     });
     

   • 删除或注释掉原URL搜索栏相关的JavaScript逻辑（如input_baseUrl的提交监听）

第三步：测试验证 #

启动Laravel服务，访问默认Swagger UI页面（通常为/api/documentation），即可看到版本下拉选择框，切换选项时会自动加载对应版本的API文档。

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