5分钟搞定！Swagger UI 默认显示示例标签的3种实用技巧
项目地址: https://gitcode.com/GitHub_Trending/sw/swagger-ui 你是否还在每次打开Swagger UI文档时手动点击切换"示例"标签？作为API文档的高频访问者，这个重复操作可能每天浪费你10分钟！本文将通过3种简单配置方法，帮你永久解决这个问题，让API文档展示效率提升50%。读完本文你将学会：通过配置文件设置全局默认、使用URL参数临时调试、以及高级自定义插件实现个性化展示。
认识Swagger UI的标签显示机制
Swagger UI（Swagger用户界面）默认将"模型"标签设为API文档的初始展示项，这对于需要查看数据结构的开发者可能合理，但运营人员和测试人员通常更关注实际请求示例。这种默认行为导致非开发人员需要额外操作才能看到关键的示例数据。
Swagger UI的标签显示逻辑主要由两个核心配置参数控制：
defaultModelRendering：控制模型的默认展示方式，可选值为"example"（示例）或"model"（模型）defaultModelExpandDepth：控制模型的默认展开深度，数值越大展开层级越多
这两个参数在官方配置文档中有详细说明，位于docs/usage/configuration.md。通过修改这些参数，我们可以轻松改变默认标签的显示行为。
方法一：修改配置文件实现全局默认
最推荐的方法是通过修改Swagger UI的配置文件，将示例标签设置为全局默认显示项。这种方式一劳永逸，适用于所有API文档的访问者。
步骤1：找到配置文件
Swagger UI的默认配置存储在src/core/config/defaults.js文件中，核心配置对象如下：
const defaultOptions = Object.freeze({
// ...其他配置
defaultModelRendering: "example", // 默认值为"example"
defaultModelExpandDepth: 1, // 默认展开深度为1
// ...其他配置
})
步骤2：修改配置参数
将defaultModelRendering参数显式设置为"example"，并确保defaultModelExpandDepth值大于0：
defaultModelRendering: "example", // 强制设置为示例标签
defaultModelExpandDepth: 2, // 适当增加展开深度
步骤3：重启应用使配置生效
修改配置后需要重新构建Swagger UI应用。如果使用Docker部署，可通过以下命令重启容器：
docker restart swagger-ui-container
这种方法的优势是所有用户访问时都会默认看到示例标签，无需个人设置。但需要有文档系统的修改权限，适合团队统一配置。
方法二：使用URL参数实现临时调试
当你没有配置文件修改权限，或需要为特定API路径临时设置示例标签时，URL参数是理想选择。Swagger UI支持通过查询字符串动态覆盖配置参数。
基础用法
在Swagger UI的访问URL后添加以下参数：
?defaultModelRendering=example
完整URL示例：
http://your-swagger-url/index.html?defaultModelRendering=example
组合参数
如需同时调整展开深度，可组合多个参数：
?defaultModelRendering=example&defaultModelExpandDepth=3
这种方式的优势是无需修改任何配置文件，适合临时调试和演示。但URL较长且无法永久保存，推荐用于测试环境或临时分享链接。
方法三：高级自定义插件实现个性化展示
对于需要更复杂控制逻辑的场景（如根据API路径动态切换标签），可以通过Swagger UI的插件系统实现自定义展示逻辑。
插件开发基础
Swagger UI的插件系统允许开发者通过JavaScript代码扩展功能。插件文件通常放在src/core/plugins/目录下，一个简单的插件结构如下：
export default function ExampleDefaultPlugin(system) {
return {
// 插件名称
name: "example-default-plugin",
// 覆盖默认配置
wrapComponents: {
// 在这里自定义标签渲染逻辑
}
};
}
实现标签切换逻辑
通过修改ExamplesSelect组件（位于src/core/components/examples-select.jsx）的默认行为，可以实现更复杂的标签显示控制。核心代码示例：
// 在插件中覆盖ExamplesSelect组件
wrapComponents: {
ExamplesSelect: (Original) => (props) => {
// 获取当前API路径
const apiPath = system.getState().getIn(["spec", "paths"]);
// 根据路径动态设置默认标签
const shouldShowExample = apiPath.includes("/public/");
return (
<Original
{...props}
defaultTab={shouldShowExample ? "example" : "model"}
/>
);
}
}
这种方法适合有编程基础的用户，可实现高度个性化的标签显示逻辑。Swagger UI的插件系统功能强大，更多高级用法可参考docs/customization/plugin-api.md。
常见问题与解决方案
配置不生效怎么办？
如果修改配置后没有看到预期效果，请检查以下几点：
- 确认配置文件路径是否正确：src/core/config/defaults.js
- 检查是否有多个配置来源冲突（URL参数优先级高于配置文件）
- 验证配置参数拼写是否正确（区分大小写）
- 确认应用已重启或重新构建
如何在Docker环境中应用配置？
使用Docker部署时，可以通过环境变量设置默认参数，无需修改源码：
docker run -d \
-e DEFAULT_MODEL_RENDERING=example \
-e DEFAULT_MODEL_EXPAND_DEPTH=2 \
--name swagger-ui \
swaggerapi/swagger-ui
相关环境变量的映射关系可在docs/usage/configuration.md的"Docker"章节找到完整列表。
总结与最佳实践
设置Swagger UI默认显示示例标签有三种主要方法，各有适用场景：
| 方法 | 优点 | 缺点 | 适用场景 |
|---|---|---|---|
| 配置文件修改 | 一劳永逸，全局生效 | 需要服务器权限 | 正式环境，团队统一配置 |
| URL参数 | 无需修改配置，即时生效 | 链接较长，无法永久保存 | 临时调试，演示分享 |
| 自定义插件 | 高度灵活，可实现复杂逻辑 | 需要编程知识 | 个性化需求，动态控制 |
最佳实践建议：在正式环境使用配置文件方法设置全局默认，开发测试阶段可结合URL参数快速调试。对于有特殊需求的团队，开发自定义插件是长期解决方案。
通过本文介绍的方法，你可以彻底告别手动切换标签的繁琐操作，让Swagger UI真正服务于API文档的高效展示。如果觉得本文有用，欢迎点赞收藏，关注获取更多Swagger UI使用技巧！
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
