DRF-Spectacular 版本化API文档生成实践指南

问题背景

在使用DRF-Spectacular为Django REST Framework项目生成API文档时，开发者可能会遇到版本化API的文档组织问题。典型场景是当项目通过URL路径区分不同API版本时（如/api/v1/和/api/v2/），生成的Swagger文档未能按预期将不同版本的API端点分开显示。

核心问题分析

当项目采用URL路径版本控制策略时，DRF-Spectacular默认会：

1. 将所有API端点混合显示在同一个标签下
2. 无法自动区分不同版本的API端点
3. 仅通过Swagger UI顶部的版本选择器提供版本切换功能

这种默认行为往往不符合开发者对版本化API文档的期望，特别是当不同版本API存在显著差异时。

解决方案

1. 正确配置版本控制类

首先需要确认Django REST Framework的版本控制类配置正确。对于URL路径版本控制，应使用NamespaceVersioning而非URLPathVersioning：

# settings.py
REST_FRAMEWORK = {
    'DEFAULT_VERSIONING_CLASS': 'rest_framework.versioning.NamespaceVersioning',
    # 其他配置...
}

2. URL命名空间配置

在URL配置中，需要为不同版本添加命名空间：

# urls.py
urlpatterns = [
    path('v1/', include('users.urls', namespace='v1')),
    path('v2/', include('users.urls', namespace='v2'))
]

3. 设置SCHEMA_PATH_PREFIX

关键配置是设置SCHEMA_PATH_PREFIX，告诉DRF-Spectacular如何识别和分组不同版本的API：

# settings.py
SPECTACULAR_SETTINGS = {
    'SCHEMA_PATH_PREFIX': '/api/v[0-9]',
    # 其他配置...
}

4. 自定义标签（可选）

对于更精细的控制，可以在视图上使用@extend_schema装饰器自定义标签：

from drf_spectacular.utils import extend_schema

@extend_schema(tags=['用户管理-v1'])
class UserViewSetV1(ModelViewSet):
    # 视图实现...

实现效果

正确配置后，Swagger文档将：

1. 按应用模块而非项目名称分组API端点
2. 清晰区分不同版本的API
3. 保持与URL结构一致的文档组织方式

最佳实践建议

1. 对于大型项目，建议结合使用路径前缀和自定义标签
2. 保持版本控制策略的一致性（URL路径/请求头/查询参数）
3. 为每个主要版本创建独立的Schema视图
4. 考虑使用API网关模式管理多版本API文档

通过以上配置，开发者可以获得清晰、结构化的版本化API文档，极大提升API的可发现性和使用体验。