Swagger UI 中如何设置示例标签为默认显示标签

在 Swagger UI 5.12.0 版本中，默认情况下会优先显示模型/架构(Model/Schema)标签，而不是示例(Examples)标签。这与之前版本的默认行为有所不同，可能会让一些习惯了旧版本行为的开发者感到困惑。

问题背景

Swagger UI 是一个流行的 API 文档工具，它提供了多个标签页来展示 API 的不同方面。其中两个重要的标签页是：

1. 模型/架构(Model/Schema)标签：显示 API 响应的数据结构定义
2. 示例(Examples)标签：显示 API 响应的具体示例数据

在较新版本的 Swagger UI 中，默认会显示模型/架构标签，而许多开发者更希望默认显示示例标签，因为示例数据通常更直观、更易于理解。

解决方案

要修改这个默认行为，关键在于 Swagger UI 的配置选项。具体来说，defaultModelRendering 这个配置项控制着默认显示的标签页。

正确的配置方法

1. 移除默认模型渲染设置：如果你在配置中明确设置了 defaultModelRendering: 'model'，这会导致默认显示模型标签。要恢复示例标签为默认，只需移除这个配置项。

2. 使用默认行为：如果不指定 defaultModelRendering 参数，Swagger UI 会使用其内置的默认行为，在较新版本中这通常意味着会显示示例标签。

配置示例

SwaggerUI({
    spec: apiSpec,
    defaultModelsExpandDepth: -1,
    dom_id: '#container',
    // 注意：这里不设置 defaultModelRendering
    showExtensions: true,
    deepLinking: true
})

技术原理

Swagger UI 的标签页渲染机制是通过配置驱动的。defaultModelRendering 参数接受以下值：

• 'model'：强制显示模型标签
• 'example'：强制显示示例标签
• 不设置：使用 Swagger UI 的默认行为

在早期版本中，Swagger UI 的默认行为是显示示例标签，这被认为对开发者更友好。但在某些版本更新后，默认行为可能发生了变化。通过不设置这个参数，你可以确保使用的是当前版本最推荐的默认行为。

最佳实践

1. 保持配置简洁：除非有特殊需求，否则不要过度配置 Swagger UI，使用默认行为通常是最佳选择。

2. 版本兼容性：如果你需要确保在不同版本间的一致性，可以明确设置 defaultModelRendering: 'example'。

3. 用户体验：考虑你的API使用者，示例数据通常比模型定义更直观，更适合作为默认显示内容。

通过理解这些配置选项，你可以轻松控制 Swagger UI 的显示行为，为你的API使用者提供更好的文档体验。