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

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

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

Swagger 配置

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

        <style>
            .swagger-ui .models,
            .swagger-ui section.models {
                display: none !important;
            }
        </style>

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

折叠全部信息

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

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

总结

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

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