如何利用DRF-YASG实现多版本API的命名空间文档展示？

1. 配置DRF版本控制 #

首先在项目settings.py中配置DRF的版本控制规则，采用URL路径版本化方式：

# settings.py
REST_FRAMEWORK = {
    'DEFAULT_VERSIONING_CLASS': 'rest_framework.versioning.URLPathVersioning',
    'DEFAULT_VERSION': 'v1',
    'ALLOWED_VERSIONS': ['v1', 'v2'],
    'VERSION_PARAM': 'version',
}

2. 为视图绑定指定版本 #

给每个视图类明确声明支持的API版本，确保DRF能正确识别版本归属：

# vehicle/views.py
from rest_framework.views import APIView
from rest_framework.response import Response

class VehicleV1View(APIView):
    version = 'v1'
    allowed_versions = ['v1']
    
    def get(self, request):
        return Response({'version': 'v1', 'resource': 'vehicle'})

class VehicleV2View(APIView):
    version = 'v2'
    allowed_versions = ['v2']
    
    def get(self, request):
        return Response({'version': 'v2', 'resource': 'vehicle'})

# warehouse/views.py
from rest_framework.views import APIView
from rest_framework.response import Response

class WarehouseV1View(APIView):
    version = 'v1'
    allowed_versions = ['v1']
    
    def get(self, request):
        return Response({'version': 'v1', 'resource': 'warehouse'})

3. 拆分版本化路由 #

将不同版本的接口路由拆分到独立的子文件中，便于Swagger精准扫描：

# vehicle/urls/v1.py
from django.urls import path
from .views import VehicleV1View

urlpatterns = [
    path('', VehicleV1View.as_view(), name='vehicle-v1'),
]

# vehicle/urls/v2.py
from django.urls import path
from .views import VehicleV2View

urlpatterns = [
    path('', VehicleV2View.as_view(), name='vehicle-v2'),
]

# warehouse/urls/v1.py
from django.urls import path
from .views import WarehouseV1View

urlpatterns = [
    path('', WarehouseV1View.as_view(), name='warehouse-v1'),
]

4. 创建版本化Swagger文档视图 #

为v1、v2分别生成独立的Swagger视图，通过patterns参数限制扫描的路由范围：

# project/urls.py
from django.urls import path, include
from rest_framework import permissions
from drf_yasg.views import get_schema_view
from drf_yasg import openapi

# V1文档：包含vehicle和warehouse的v1接口
schema_view_v1 = get_schema_view(
    openapi.Info(
        title="API V1",
        default_version='v1',
        description="API Version 1 包含Vehicle和Warehouse端点",
    ),
    public=True,
    permission_classes=(permissions.AllowAny,),
    patterns=[
        path('api/v1/vehicle/', include('vehicle.urls.v1')),
        path('api/v1/warehouse/', include('warehouse.urls.v1')),
    ],
)

# V2文档：仅包含vehicle的v2接口
schema_view_v2 = get_schema_view(
    openapi.Info(
        title="API V2",
        default_version='v2',
        description="API Version 2 仅包含Vehicle端点",
    ),
    public=True,
    permission_classes=(permissions.AllowAny,),
    patterns=[
        path('api/v2/vehicle/', include('vehicle.urls.v2')),
    ],
)

5. 配置主路由 #

将版本化接口和文档路由添加到项目主URL配置：

# project/urls.py
urlpatterns = [
    # 版本化API接口
    path('api/v1/vehicle/', include('vehicle.urls.v1')),
    path('api/v2/vehicle/', include('vehicle.urls.v2')),
    path('api/v1/warehouse/', include('warehouse.urls.v1')),
    
    # 版本化Swagger文档
    path('api/v1/doc/', schema_view_v1.with_ui('swagger', cache_timeout=0), name='schema-v1'),
    path('api/v2/doc/', schema_view_v2.with_ui('swagger', cache_timeout=0), name='schema-v2'),
]

原问题排查 #

之前Swagger未显示接口的核心原因：

• 视图未明确绑定version和allowed_versions，DRF无法识别版本归属
• Swagger视图未限制扫描的路由范围，导致无法匹配到对应版本的接口
• 版本控制类配置错误，未采用URLPathVersioning适配URL路径版本模式

按照上述步骤配置后，/api/v1/doc会展示vehicle和warehouse的v1接口，/api/v2/doc仅展示vehicle的v2接口，完全满足需求。

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