Swagger如何默认展开所有API子项？

Question

在使用Swagger UI展示RESTful API文档时，如何默认展开所有API子项（如接口方法、参数、响应示例等）是一个常见需求。默认情况下，Swagger UI会折叠所有操作，需手动点击展开，影响开发和测试效率。开发者常问：能否通过配置使所有接口在页面加载时自动展开？尤其是在管理后台或内部系统中，希望快速查看全部接口详情。虽然Swagger本身未提供直接配置项，但可通过自定义Swagger UI的布局参数（如`docExpansion`和`defaultModelsExpandDepth`）结合注入JavaScript脚本实现默认展开。如何正确设置这些参数并兼容不同版本的Swagger UI（如Swagger UI 3.x 或 Swagger 2.x），成为实际部署中的典型技术问题。

Answer 1

如何在Swagger UI中默认展开所有API子项

1. 背景与问题提出

在现代微服务架构开发中，RESTful API文档的可视化展示至关重要。Swagger UI作为最流行的API文档工具之一，广泛应用于Spring Boot、Node.js等后端框架中。然而，默认情况下，Swagger UI会将所有接口操作（Operations）折叠显示，用户必须手动点击每个接口才能查看其参数、请求体、响应示例等详细信息。

对于内部系统或管理后台，开发、测试和联调人员往往希望在页面加载时即看到所有接口的完整结构，以提升查阅效率。因此，“能否让Swagger UI默认展开所有API子项”成为一个高频技术诉求。

2. 核心配置参数解析

Swagger UI提供了一些可配置的布局选项，用于控制文档的初始展开状态。关键参数如下：

参数名	作用说明	适用版本	可选值
docExpansion	控制操作（接口方法）的初始展开层级	Swagger UI 3.x / 2.x	'none', 'list', 'full'
defaultModelsExpandDepth	控制模型（Models）的默认展开深度	Swagger UI 3.x / 2.x	整数（0=折叠，3=三层展开）
defaultExpandedDepth	控制嵌套对象的展开层级（部分版本支持）	Swagger UI 3.x	整数

3. 配置实现方式（基于Swagger UI 3.x）

以Springfox或SpringDoc OpenAPI为例，可通过Java配置类注入自定义参数：

    @Configuration
    public class SwaggerConfig {
        
        @Bean
        public OpenAPI customOpenAPI() {
            return new OpenAPI()
                .info(new Info().title("API文档").version("1.0"));
        }

        @Bean
        public GroupedOpenApi publicApi() {
            return GroupedOpenApi.builder()
                .group("public")
                .pathsToMatch("/api/**")
                .build();
        }
    }
    

随后，在index.html或前端资源中覆盖Swagger UI初始化逻辑：

    window.onload = function() {
        const ui = SwaggerUIBundle({
            url: "/v3/api-docs",
            dom_id: '#swagger-ui',
            docExpansion: 'full', // 关键：展开所有操作
            defaultModelsExpandDepth: -1, // 展开所有模型
            defaultModelExpandDepth: 5,
            presets: [
                SwaggerUIBundle.presets.apis,
                SwaggerUIStandalonePreset
            ],
            layout: "StandaloneLayout"
        });

        window.ui = ui;
    };
    

4. 兼容性处理：Swagger UI 2.x vs 3.x

不同版本的Swagger UI在参数命名和行为上存在差异，需特别注意：

• Swagger UI 2.x：使用docExpansion: 'list'可展开接口列表，但不会自动展开参数和响应；需额外注入JS脚本模拟点击事件。
• Swagger UI 3.x+：支持docExpansion: 'full'，可直接展开所有操作及其子项。
• 某些旧版Springfox（如2.x）仍基于Swagger 2.0规范，需升级至SpringDoc OpenAPI以获得更好支持。

5. JavaScript脚本增强：强制展开未暴露参数

当配置不足以完全展开所有内容时，可通过DOM操作补足：

    setTimeout(() => {
        // 模拟点击所有折叠按钮
        document.querySelectorAll('.opblock-summary').forEach(el => {
            if (!el.nextElementSibling.classList.contains('open')) {
                el.click(); // 触发展开
            }
        });

        // 展开所有模型定义
        document.querySelectorAll('.model-toggle').forEach(btn => {
            if (btn.textContent.trim() === 'more >') {
                btn.click();
            }
        });
    }, 1000); // 延迟执行确保渲染完成
    

6. 自定义Swagger UI部署流程图

graph TD
            A[启动应用] --> B{是否集成Swagger?}
            B -- 是 --> C[加载Swagger配置]
            C --> D[设置docExpansion=full]
            D --> E[设置defaultModelsExpandDepth=-1]
            E --> F[注入自定义JS脚本]
            F --> G[渲染Swagger UI界面]
            G --> H[页面加载完成]
            H --> I[执行DOM操作展开剩余项]
            I --> J[用户看到全部展开的API]

7. 实践建议与最佳配置组合

结合多项目实践经验，推荐以下配置策略：

1. 优先使用SpringDoc OpenAPI替代老旧Springfox，获得更好的Swagger 3.x支持。
2. 在index.html中显式设置docExpansion: 'full'和defaultModelsExpandDepth: -1。
3. 添加延迟执行的JavaScript脚本，确保异步渲染后的元素也被展开。
4. 对内网系统可考虑缓存定制版Swagger UI资源，避免每次构建重复修改。
5. 通过Nginx或前端代理统一注入脚本，实现跨服务集中管理。
6. 测试不同浏览器兼容性，尤其是IE11等老旧环境下的行为差异。
7. 记录团队内部Swagger配置规范，形成标准化文档。
8. 监控加载性能，避免因大量展开导致页面卡顿。
9. 提供“收起/展开全部”快捷按钮，增强用户体验。
10. 定期评估是否需要切换至Redoc等替代方案以满足更复杂需求。