Django集成Swagger的两种实现方案全指南

一、方案选型对比

1.1 核心方案对比

graph TD
    A[Swagger集成方案] --> B[drf-yasg]
    A --> C[django-rest-swagger]
    B --> D[功能全面]
    B --> E[支持OpenAPI 3.0]
    C --> F[简单易用]
    C --> G[兼容旧版]

特性	drf-yasg	django-rest-swagger
Django版本支持	2.2+	1.11+
DRF版本支持	3.10+	3.7+
OpenAPI支持	2.0 & 3.0	2.0
可视化交互	支持	支持
Schema生成方式	自动+手动	自动
认证配置	灵活	基础

二、drf-yasg方案实现

2.1 环境安装

pip install drf-yasg
# 依赖包
pip install coreapi pyyaml uritemplate

2.2 基础配置

# settings.py
INSTALLED_APPS += [
    'drf_yasg',
]

# urls.py
from drf_yasg.views import get_schema_view
from drf_yasg import openapi

schema_view = get_schema_view(
    openapi.Info(
        title="API文档",
        default_version='v1',
        description="项目接口文档",
        terms_of_service="https://example.com",
        contact=openapi.Contact(email="contact@example.com"),
        license=openapi.License(name="BSD License"),
    ),
    public=True,
    permission_classes=(permissions.AllowAny,),
)

urlpatterns = [
    path('swagger/', schema_view.with_ui('swagger', cache_timeout=0)),
    path('redoc/', schema_view.with_ui('redoc', cache_timeout=0)),
]

2.3 高级配置示例

# 自定义认证配置
schema_view = get_schema_view(
    ...
    authentication_classes=(BasicAuthentication,),
)

# 接口过滤配置
from drf_yasg.inspectors import SwaggerAutoSchema

class CustomAutoSchema(SwaggerAutoSchema):
    def get_tags(self, operation_keys):
        if 'v2' in operation_keys:
            return ['v2']
        return super().get_tags(operation_keys)

SWAGGER_SETTINGS = {
    'DEFAULT_AUTO_SCHEMA_CLASS': 'path.to.CustomAutoSchema',
    'SECURITY_DEFINITIONS': {
        'Bearer': {
            'type': 'apiKey',
        }
    }
}

三、django-rest-swagger方案

3.1 环境安装

pip install django-rest-swagger

3.2 基础配置

# settings.py
INSTALLED_APPS += [
    'rest_framework_swagger',
]

# urls.py
from rest_framework_swagger.views import get_swagger_view

schema_view = get_swagger_view(title='API文档')

urlpatterns = [
    path('docs/', schema_view),
]

3.3 扩展配置

# 自定义配置
SWAGGER_SETTINGS = {
    'SECURITY_DEFINITIONS': {
        'api_key': {
            'type': 'apiKey',
            'in': 'header',
            'name': 'Authorization'
        }
    },
    'USE_SESSION_AUTH': False,
    'JSON_EDITOR': True,
}

# 视图级配置示例
from rest_framework_swagger import renderers
from rest_framework.decorators import api_view, renderer_classes

@api_view(['GET'])
@renderer_classes([renderers.OpenAPIRenderer, renderers.SwaggerUIRenderer])
def schema_view(request):
    generator = schemas.SchemaGenerator(title='API Docs')
    return Response(generator.get_schema(request=request))

四、接口文档注解规范

4.1 方法注释规范

from drf_yasg.utils import swagger_auto_schema

@swagger_auto_schema(
    operation_description="获取用户详情",
    manual_parameters=[
        openapi.Parameter(
            'id',
            openapi.IN_PATH,
            description="用户ID",
            type=openapi.TYPE_INTEGER
        )
    ],
    responses={
        200: openapi.Response('成功返回', UserSerializer),
        404: '用户不存在'
    }
)
def retrieve(self, request, pk=None):
    pass

4.2 序列化器字段说明

class UserSerializer(serializers.ModelSerializer):
    class Meta:
        model = User
        fields = '__all__'
        ref_name = 'API_User'
        
    email = serializers.EmailField(
        help_text="用户邮箱",
        required=True
    )
    username = serializers.CharField(
        help_text="登录账号",
        max_length=50
    )

五、安全配置方案

5.1 JWT认证集成

# drf-yasg配置示例
SWAGGER_SETTINGS = {
    'SECURITY_DEFINITIONS': {
        'Bearer': {
            'type': 'apiKey',
            'name': 'Authorization',
            'in': 'header'
        }
    },
    'LOGIN_URL': '/admin/login/',
    'LOGOUT_URL': '/admin/logout/'
}

# 权限控制装饰器
from drf_yasg.utils import swagger_auto_schema

@swagger_auto_schema(
    security=[{'Bearer': []}],
    operation_security=['Bearer']
)
@permission_classes([IsAuthenticated])
def list(self, request):
    pass

5.2 访问限制配置

# 生产环境限制访问
from django.conf import settings

if not settings.DEBUG:
    urlpatterns += [
        path('swagger/', 
            login_required(schema_view.with_ui('swagger', cache_timeout=0)),
            name='swagger'),
    ]

六、性能优化建议

6.1 缓存策略

# 使用缓存装饰器
from django.views.decorators.cache import cache_page

urlpatterns = [
    path('swagger/', cache_page(60 * 60)(schema_view.with_ui('swagger', cache_timeout=0))),
]

# 或使用缓存后端
CACHES = {
    'swagger': {
        'BACKEND': 'django.core.cache.backends.filebased.FileBasedCache',
        'LOCATION': '/var/tmp/swagger_cache',
    }
}

6.2 分模块加载

# 按应用拆分文档
app_patterns = [
    path('users/', include('users.urls')),
]

doc_patterns = [
    path('swagger/users/', 
        get_schema_view(
            patterns=app_patterns,
            title="用户模块API"
        ).with_ui('swagger')),
]

七、常见问题解决

7.1 问题排查清单

问题现象	可能原因	解决方案
页面空白/加载失败	静态文件未加载	配置STATIC_URL
接口未显示	未注册到路由	检查urls.py包含
参数显示不全	缺少swagger_auto_schema	添加方法装饰器
认证失败	未配置SECURITY_DEFINITIONS	完善安全配置
嵌套序列化器显示异常	ref_name冲突	在Meta中指定ref_name

7.2 自定义错误处理

# 异常处理中间件
class SwaggerExceptionMiddleware:
    def __init__(self, get_response):
        self.get_response = get_response

    def __call__(self, request):
        response = self.get_response(request)
        if '/swagger/' in request.path and response.status_code == 404:
            return HttpResponseNotFound("""
                <h1>文档未找到</h1>
                <p>请检查服务是否正常运行</p>
            """)
        return response

八、企业级实践方案

8.1 多版本API文档

# 版本化文档配置
v1_schema_view = get_schema_view(
    openapi.Info(title="API V1", default_version='v1'),
    public=True,
    patterns=[path('api/v1/', include('api.v1.urls'))],
)

v2_schema_view = get_schema_view(
    openapi.Info(title="API V2", default_version='v2'),
    public=True,
    patterns=[path('api/v2/', include('api.v2.urls'))],
)

urlpatterns = [
    path('docs/v1/', v1_schema_view.with_ui('swagger')),
    path('docs/v2/', v2_schema_view.with_ui('redoc')),
]

8.2 自动化文档流水线

graph LR
    A[代码提交] --> B[CI构建]
    B --> C[自动生成文档]
    C --> D[部署到文档服务器]
    D --> E[邮件通知团队]

实现脚本示例：

# CI脚本片段
python manage.py generateschema > openapi-schema.yml
aws s3 cp openapi-schema.yml s3://docs-bucket/api-${CI_COMMIT_SHA}.yml

九、扩展功能集成

9.1 接口测试集成

# 在swagger中增加测试按钮
SWAGGER_SETTINGS = {
    'DEFAULT_FIELD_INSPECTORS': [
        'drf_yasg.inspectors.CamelCaseJSONFilter',
        'drf_yasg.inspectors.ReferencingSerializerInspector',
        'drf_yasg.inspectors.RelatedFieldInspector',
        'drf_yasg.inspectors.ChoiceFieldInspector',
        'drf_yasg.inspectors.FileFieldInspector',
        'drf_yasg.inspectors.DictFieldInspector',
        'drf_yasg.inspectors.HiddenFieldInspector',
        'drf_yasg.inspectors.RecursiveFieldInspector',
        'drf_yasg.inspectors.SerializerMethodFieldInspector',
        'drf_yasg.inspectors.SimpleFieldInspector',
        'drf_yasg.inspectors.StringDefaultFieldInspector',
    ],
    'DEFAULT_FILTER_INSPECTORS': [
        'path.to.CustomFilterInspector'
    ],
    'EXTERNAL_DOCS': {
        'description': '接口测试指南',
        'url': '/static/test_guide.html'
    }
}

9.2 文档多语言支持

# 国际化配置
from django.utils.translation import gettext_lazy as _

class MultiLanguageSchemaView(SchemaView):
    def get(self, request, *args, **kwargs):
        lang = request.GET.get('lang', 'en')
        if lang == 'zh':
            self.info.title = _("API文档")
            self.info.description = _("项目接口文档")
        return super().get(request, *args, **kwargs)

两种方案各有优势：