Django中如何配置drf_yasg实现OpenAPI文档多版本分离展示

drf-yasg原生支持分版本生成独立Schema、配置版本切换下拉框，无需引入额外依赖，按以下步骤配置即可实现和.NET技术栈ApiVersioning+Swagger一致的使用体验。

1. 为每个API版本定义独立的Schema实例 #

核心是通过get_schema_view的patterns参数限定当前Schema扫描的路由范围，避免不同版本接口混显。
在项目根路由文件（通常是urls.py）中添加如下配置：

from rest_framework import permissions
from drf_yasg.views import get_schema_view
from drf_yasg import openapi
from django.urls import path, include

# v1版本文档Schema配置
schema_v1 = get_schema_view(
    openapi.Info(
        title="项目API文档",
        default_version="v1",
        description="v1版本全量接口说明",
    ),
    # 仅扫描路由前缀为api/v1/的接口
    patterns=[path("api/v1/", include("your_app.urls_v1"))],
    permission_classes=[permissions.AllowAny],
)

# v2版本文档Schema配置
schema_v2 = get_schema_view(
    openapi.Info(
        title="项目API文档",
        default_version="v2",
        description="v2版本全量接口说明",
    ),
    # 仅扫描路由前缀为api/v2/的接口
    patterns=[path("api/v2/", include("your_app.urls_v2"))],
    permission_classes=[permissions.AllowAny],
)

如果你将不同版本的路由拆分到了独立的urls文件，也可以直接给get_schema_view传入urlconf="your_project.urls_v1"参数替代patterns，效果一致。

2. 配置路由与Swagger UI版本参数 #

分别为每个版本的Schema生成独立的json访问地址，再给Swagger UI传入多版本地址配置，前端会自动渲染版本选择下拉框：

urlpatterns = [
    # 原有业务版本路由
    path("api/v1/", include("your_app.urls_v1")),
    path("api/v2/", include("your_app.urls_v2")),

    # 各版本独立Schema json地址
    path("swagger/v1.json", schema_v1.without_ui(cache_timeout=0), name="schema-v1-json"),
    path("swagger/v2.json", schema_v2.without_ui(cache_timeout=0), name="schema-v2-json"),

    # Swagger UI 入口
    path(
        "swagger/",
        schema_v1.with_ui(
            "swagger",
            cache_timeout=0,
            config={
                # 配置多版本文档地址，UI自动生成下拉选择框
                "urls": [
                    {"name": "v1 版本", "url": "/swagger/v1.json"},
                    {"name": "v2 版本", "url": "/swagger/v2.json"},
                ],
                # 默认展示的版本
                "urls.primaryName": "v1 版本",
            },
        ),
        name="swagger-ui",
    ),
]

配置校验 #

配置完成后重启服务，强制清空浏览器缓存访问/swagger/路径，即可在页面顶部看到版本选择下拉框，切换选项时会自动加载对应版本的接口列表，不会再出现多版本接口混在同一页面的问题。

注意点 #

• 代码中your_app、your_project占位符请替换为你项目实际的应用、模块名称
• 该配置兼容DRF自带的URLPathVersioning、NamespaceVersioning等所有官方版本方案，不需要修改原有业务路由逻辑
• 不同版本文档的鉴权规则可以直接在对应schema_vx实例的permission_classes中单独配置

内容的提问来源于stack exchange，提问作者Fabsi