定制Django REST FrameworkSwagger教程：从零开始到美观文档

本文将详细介绍如何在Django REST Framework（DRF）项目中自定义Swagger，以便创建更美观、易用的API接口文档。首先，我们将回顾一下环境设置，包括使用的Django版本（1.11.6）、DRF版本（3.7.1）以及与Swagger相关的库，如django-rest-swagger（2.1.2）等。由于3.6版本与3.7版本在Swagger集成上存在一些差异，但核心概念是一致的，本文将以3.7.1为例进行讲解。 步骤一：配置更改 在`settings.py`文件中，确保已将'rest_framework'添加到`INSTALLED_APPS`列表中，以便让Django知道要启用REST框架及其Swagger功能： ```python INSTALLED_APPS = [ 'django.contrib.admin', 'django.contrib.auth', 'django.contrib.contenttypes', 'django.contrib.sessions', 'django.contrib.messages', # 添加这一行 'rest_framework', # 其他应用... ] ``` 步骤二：启用Swagger 在`REST_FRAMEWORK`部分，我们需要启用Swagger的文档生成功能，并配置相关参数。例如： ```python REST_FRAMEWORK = { 'DEFAULT_SCHEMA_CLASS': 'rest_framework.schemas.coreapi.AutoSchema', 'DEFAULT_PARSER_CLASSES': ( 'rest_framework.parsers.JSONParser', 'rest_framework.parsers.FormParser', 'rest_framework.parsers.MultiPartParser' ), 'DEFAULT_RENDERER_CLASSES': ( 'rest_framework.renderers.JSONRenderer', 'rest_framework.renderers.BrowsableAPIRenderer', ), 'DOC_INCLUDE_REQUEST_HEADERS': False, # 隐藏默认的请求头 'SWAGGER_SETTINGS': { 'USE_SESSION_AUTH': False, # 关闭Swagger认证 'SECURITY_DEFINITIONS': { 'api_key': { 'type': 'apiKey', 'name': 'Authorization', 'in': 'header' } }, 'info': { 'title': 'Your Project API', # API文档标题 'description': 'This is an example of custom Swagger documentation using Django REST Framework.', # 描述文档内容 'version': '1.0.0', }, 'exclude_namespaces': [], # 可选，排除不需要显示的命名空间 } } ``` 在这里，我们设置了`DOC_INCLUDE_REQUEST_HEADERS`为False来隐藏默认请求头，还配置了基本的API安全定义和文档信息。`SECURITY_DEFINITIONS`定义了如何验证API密钥。 步骤三：自定义视图和序列化器 为了提供更具体的自定义描述，你可以重写或扩展`AutoSchema`类，以实现更复杂的参数解析和数据展示。例如，为模型视图添加详细的字段描述： ```python from rest_framework import serializers, generics class CustomAutoSchema(AutoSchema): def get_field_info(self, field): info = super().get_field_info(field) if isinstance(field, serializers.ModelSerializer): for nested_field in field.fields.values(): info['properties'][nested_field.field_name] = self.get_field_info(nested_field) return info class YourModelViewSet(generics.ListCreateAPIView): queryset = YourModel.objects.all() serializer_class = YourModelSerializer schema = CustomAutoSchema() ``` 这将在Swagger文档中展示出模型字段的详细描述。 步骤四：启动Swagger UI 安装并配置Swagger UI以访问自定义的API文档。在项目的urls.py中添加URL路径，指向Swagger的HTML文件： ```python from drf_yasg.views import get_schema_view from drf_yasg import openapi schema_view = get_schema_view( openapi.Info( title="Your Project API", default_version='v1', description="API文档", ), public=True, permission_classes=[], ) urlpatterns += [ path('api/docs/', schema_view.with_ui('swagger', cache_timeout=0), name='schema-swagger-ui'), ] ``` 现在，当用户访问`/api/docs/`时，他们将看到一个美观且功能完整的Swagger界面，可以查看、测试和操作API。 总结，本文详细介绍了在Django REST Framework中自定义Swagger的过程，包括配置、视图定制和启动Swagger UI。理解这些步骤后，可以根据项目需求进一步个性化和优化文档体验。