【Dv3Admin】drf-yasg Swagger UI 配置与优化实践

随着API文档自动化需求的增长，Swagger UI已成为Django项目接口文档管理的核心工具之一。如何根据实际项目需求，优化Swagger界面与交互体验，成为开发者关注的重点。

本文梳理Swagger UI在drf-yasg框架中的常见定制方法，包括隐藏Model区域、折叠API分组、核心配置参数详解等，帮助高效构建清晰、易用的接口文档页面。

文章目录

• Swagger 配置
• 优化实践
• • 隐藏Model模块
  • 折叠全部信息
• 总结

Swagger 配置

SWAGGER_SETTINGS 是 Django REST Framework 项目中用于定制 Swagger UI 行为的重要参数集合，能够针对接口文档的认证方式、页面显示风格、分组与排序规则、接口参数编辑体验、分层粒度、静态资源加载等多维度进行灵活配置。通过合理设置各项参数，不仅可以提升文档的交互性与可读性，还能满足团队在接口调试、安全访问、风格统一等方面的多样化需求。在实际应用中，核心配置项通常围绕接口分组方式、接口排序、认证机制与文档展示进行调整，能够有效提升开发、测试与运维人员在API对接过程中的效率和体验。同时，针对不同的业务场景，项目还可以通过自定义schema生成类、字段和过滤器展示方式，以及静态资源拓展，为接口文档提供更专业和贴合实际的展示效果，进一步增强文档的实用性和可维护性。

参数名 作用与详细说明 SECURITY_DEFINITIONS 用于配置接口文档的认证方式。例如配置 Basic Auth、Bearer Token 等，开发者可在 Swagger UI 直接输入认证信息调试接口。常见写法如：{\"basic\": {\"type\": \"basic\"}}。 LOGIN_URL 指定文档页面的登录URL，未登录用户访问Swagger UI会自动跳转到该地址。通常配置为站点实际的登录路由。 LOGOUT_URL 指定文档页面的登出URL，点击登出按钮时跳转的地址。可用来安全退出登录态。 DOC_EXPANSION 控制接口分组默认的展开方式。取值\"none\"表示全部折叠，\"list\"表示分组展开接口折叠，\"full\"为分组和接口都展开。通常推荐用\"none\"以提升文档可读性。 APIS_SORTER 控制接口分组（tags）的排序方式。设置为\"alpha\"表示按字母序排序，便于快速定位。 JSON_EDITOR 启用后，接口请求参数中的 JSON 输入框将变为可视化编辑器，便于编辑复杂结构的参数。设置为 True 启用。 OPERATIONS_SORTER 控制同一分组下接口（GET/POST/PUT/DELETE等）的排序方式。设置为\"alpha\"时，接口按字母顺序排列。 VALIDATOR_URL 指定Swagger UI的在线校验服务地址。通常设为 None，表示不使用Swagger官方的校验API。可避免网络请求报错。 AUTO_SCHEMA_TYPE 控制 API 分组的分层粒度，0、1、2 分别对应不同的URL层级分组，影响文档分组方式。具体取值根据实际API设计需求调整。 DEFAULT_AUTO_SCHEMA_CLASS 指定默认的自动schema生成类，通常用于自定义字段展示、接口注释格式等高级功能。 SHOW_REQUEST_HEADERS 控制是否在接口调试时显示请求头。设置为 True 可以查看和编辑请求头信息。 USE_SESSION_AUTH 是否启用 session 认证，便于开发阶段基于Cookie自动带登录态进行接口调试。默认为 False。 EXTRA_STATIC_FILES 指定Swagger UI加载的额外静态文件，适用于自定义样式或脚本扩展。 DEFAULT_FIELD_INSPECTORS 用于定制字段类型在schema中的呈现方式，适用于复杂场景下的文档定制。 DEFAULT_FILTER_INSPECTORS 控制过滤器在schema中的展示方式，便于前端理解过滤参数。

全部参数样例可以参考下面的内容，复制到项目中进行修改即可。

SWAGGER_SETTINGS = { \"SECURITY_DEFINITIONS\": { # 配置接口文档的认证方式（常用 basic/basic auth） \"basic\": {\"type\": \"basic\"}, # \"Bearer\": {\"type\": \"apiKey\", \"in\": \"header\", \"name\": \"Authorization\"}, # 可选：Bearer Token认证示例 }, \"LOGIN_URL\": \"apiLogin/\", # 登录页URL，未登录时跳转此页面（可选，按实际项目路由） \"LOGOUT_URL\": \"rest_framework:logout\", # 登出URL，点击登出按钮跳转此地址（可选） \"DOC_EXPANSION\": \"none\", # 控制接口分组展开方式：\"none\"=全部折叠，\"list\"=分组展开接口折叠，\"full\"=全部展开 \"APIS_SORTER\": \"alpha\",  # 接口分组(tag)排序方式：\"alpha\"按字母升序，可选\"alpha\"或\"method\" \"OPERATIONS_SORTER\": \"alpha\", # 同组下接口排序方式，\"alpha\"按方法名字母升序，可选\"alpha\"或\"method\" \"JSON_EDITOR\": True,  # 启用JSON编辑器，便于填写复杂参数，True/False（可选） \"VALIDATOR_URL\": None,  # 不使用Swagger官方的schema校验服务，避免多余外网请求（可选） \"AUTO_SCHEMA_TYPE\": 1,  # url分组层级，0/1/2，影响API文档分组显示（可选，按实际需要） \"DEFAULT_AUTO_SCHEMA_CLASS\": \"dvadmin.utils.swagger.CustomSwaggerAutoSchema\", # 自定义schema生成类（可选，按项目定制） # 以下为可选高级参数（如无特别需求可省略） \"SHOW_REQUEST_HEADERS\": True, # 是否显示请求头信息，便于调试（可选） \"USE_SESSION_AUTH\": True, # 启用session认证，登录后可自动带cookie调试（可选，常用于开发环境） \"EXTRA_STATIC_FILES\": [], # 自定义Swagger UI加载的额外静态文件，如自定义样式脚本等（可选） \"DEFAULT_FIELD_INSPECTORS\": [], # 定制字段类型的schema展示方式，复杂文档定制时使用（可选） \"DEFAULT_FILTER_INSPECTORS\": [], # 控制过滤器schema展示方式，复杂场景可用（可选）}

优化实践

在实际开发中，Swagger UI默认界面经常出现不必要的信息堆叠，如Model模块和接口分组全部展开，影响文档的整体可读性与操作效率。通过定制drf-yasg的静态页面源码与合理配置SWAGGER_SETTINGS，可以实现隐藏Model区域与折叠所有分组的效果，使API文档更加简洁明了，适应复杂项目的管理与浏览需求。

隐藏Model模块

这个 model 区域基本用不到可以隐藏。

但是在 Swagger 的配置中是无法操作，需要修改页面源码。在项目目录下找到 drf-yasg 目录下的 swagger-ui.html ，在 {% block main_styles %} 下添加

  .swagger-ui .models, .swagger-ui section.models { display: none !important; } 

保存后，刷新 Swagger 页面即可生效（如还不生效，重启服务、强制刷新页面）。

折叠全部信息

在 Swagger UI 的 SWAGGER_SETTINGS 配置中，\"DOC_EXPANSION\": \"none\" 用于控制接口文档页面分组的默认展开行为。将该参数设置为 \"none\" 时，Swagger UI 页面中的所有 API 分组在页面加载时全部处于折叠状态，用户需要手动点击分组标题才能展开查看接口详情。这种设置能够有效提升文档的可读性，特别是在接口数量较多或分组较为复杂的项目中，避免页面初始加载时因分组过多而导致信息堆叠、影响整体浏览体验。

SWAGGER_SETTINGS = { ..... \"DOC_EXPANSION\": \"none\", # 控制文档分组展开方式，推荐\"none\"全部折 .....}

总结

合理定制Swagger UI能极大提升API文档的可读性与交互体验。通过隐藏无用的Model区域、调整分组展开方式、精细配置SWAGGER_SETTINGS参数，可以实现更贴合项目实际的接口文档展示与调试环境。这些配置不仅方便开发和测试，也为后期的维护和接口对接工作提供了坚实基础。

面向未来，接口文档的自动化与定制将继续深入，更多针对不同业务场景的展示与交互方案会不断涌现。持续关注社区和框架更新，适时引入新特性，有助于保持文档管理的高效与先进性。