【后端】【django drf】django自动导出优雅的api文档的写法
Django DRF API 编写规范（包含 OpenAPI 生成规则）
为了确保 Django DRF API 代码的可维护性、可扩展性，同时生成清晰、规范、结构层次分明的 OpenAPI 文档，必须遵循以下规则。
一、使用 drf-spectacular 生成 OpenAPI 文档
（一）安装 drf-spectacular
pip install drf-spectacular
（二）配置 settings.py
INSTALLED_APPS = [
'drf_spectacular',
'rest_framework',
]
REST_FRAMEWORK = {
'DEFAULT_SCHEMA_CLASS': 'drf_spectacular.openapi.AutoSchema',
}
SPECTACULAR_SETTINGS = {
'TITLE': "My API",
'DESCRIPTION': "项目 API 文档",
'VERSION': '1.0.0',
'SERVE_INCLUDE_SCHEMA': False,
'SWAGGER_UI_SETTINGS': {
'deepLinking': True,
'defaultModelRendering': 'model',
'defaultModelsExpandDepth': 2,
},
}
（三）添加 OpenAPI 路由
from drf_spectacular.views import SpectacularAPIView, SpectacularSwaggerView, SpectacularRedocView
urlpatterns = [
path('api/schema/', SpectacularAPIView.as_view(), name='schema'),
path('api/docs/', SpectacularSwaggerView.as_view(url_name='schema'), name='swagger-ui'),
path('api/redoc/', SpectacularRedocView.as_view(url_name='schema'), name='redoc'),
]
- 访问
/api/docs/：Swagger UI - 访问
/api/redoc/：ReDoc
二、编写清晰的 API 视图
（一）使用 @extend_schema 详细描述 API
from drf_spectacular.utils import extend_schema
from rest_framework.viewsets import ModelViewSet
from .models import User
from .serializers import UserSerializer
class UserViewSet(ModelViewSet):
queryset = User.objects.all()
serializer_class = UserSerializer
@extend_schema(
summary="获取用户列表",
description="返回所有用户的列表，支持分页。",
responses={200: UserSerializer(many=True)}
)
def list(self, request, *args, **kwargs):
return super().list(request, *args, **kwargs)
规则
@extend_schema(summary="简要说明", description="详细描述")用于丰富 API 文档。responses={200: UserSerializer(many=True)}确保文档显示正确的返回格式。
三、在 serializers.py 里优化文档
（一）使用 help_text 和 verbose_name 提供字段说明
from rest_framework import serializers
from .models import User
class UserSerializer(serializers.ModelSerializer):
username = serializers.CharField(help_text="用户名，唯一标识")
email = serializers.EmailField(help_text="用户的电子邮箱地址")
class Meta:
model = User
fields = ["id", "username", "email"]
规则
help_text：用于 API 文档中展示字段说明。verbose_name：如果模型里定义了，会自动生成为字段的描述。
四、使用 @extend_schema_view 让 ViewSet 更清晰
如果 ViewSet 里的方法较多，每个方法都写 @extend_schema 会很冗余，可以直接给整个 ViewSet 统一定义：
from drf_spectacular.utils import extend_schema_view
@extend_schema_view(
list=extend_schema(summary="获取用户列表"),
retrieve=extend_schema(summary="获取单个用户详情"),
create=extend_schema(summary="创建新用户"),
update=extend_schema(summary="更新用户信息"),
partial_update=extend_schema(summary="部分更新用户信息"),
destroy=extend_schema(summary="删除用户"),
)
class UserViewSet(ModelViewSet):
queryset = User.objects.all()
serializer_class = UserSerializer
规则
@extend_schema_view统一管理ViewSet方法的文档信息，避免重复写@extend_schema。- 适用于
ModelViewSet。
五、给请求参数提供明确说明
（一）在 serializers.py 里定义 API 请求体
from drf_spectacular.utils import OpenApiExample, extend_schema
from rest_framework import serializers
class UserCreateSerializer(serializers.Serializer):
username = serializers.CharField(help_text="用户的唯一标识")
email = serializers.EmailField(help_text="用户的电子邮箱")
password = serializers.CharField(write_only=True, help_text="密码，至少8位")
class Meta:
fields = ["username", "email", "password"]
（二）在 views.py 里使用
from drf_spectacular.utils import extend_schema
@extend_schema(
request=UserCreateSerializer,
responses={201: UserSerializer},
examples=[
OpenApiExample(
name="示例用户",
value={"username": "john_doe", "email": "[email protected]", "password": "securepassword"},
request_only=True
)
]
)
def create(self, request, *args, **kwargs):
return super().create(request, *args, **kwargs)
规则
request=UserCreateSerializer指定 API 需要的请求参数格式。examples提供示例数据，方便前端查看。
六、使用 OpenApiParameter 定义查询参数
（一）示例
from drf_spectacular.utils import OpenApiParameter
@extend_schema(
parameters=[
OpenApiParameter(name="username", description="按照用户名筛选", required=False, type=str),
OpenApiParameter(name="page", description="分页参数，默认为1", required=False, type=int),
],
responses={200: UserSerializer(many=True)}
)
def list(self, request, *args, **kwargs):
return super().list(request, *args, **kwargs)
规则
OpenApiParameter用于 API 查询参数说明。description="说明"确保前端易于理解。
七、示例 API 端点
最终效果（访问 /api/docs/）
paths:
/users/:
get:
summary: "获取用户列表"
description: "返回所有用户的列表，支持分页"
parameters:
- name: username
in: query
description: "按照用户名筛选"
required: false
schema:
type: string
- name: page
in: query
description: "分页参数，默认为1"
required: false
schema:
type: integer
responses:
"200":
description: "成功获取用户列表"
content:
application/json:
schema:
type: array
items:
$ref: "#/components/schemas/User"
/users/{id}/:
get:
summary: "获取单个用户详情"
description: "返回指定 ID 的用户信息"
responses:
"200":
description: "成功获取用户"
content:
application/json:
schema:
$ref: "#/components/schemas/User"
总结
drf-spectacular是 Django DRF 生成 OpenAPI 文档的最佳选择。- 使用
@extend_schema为 API 方法添加详细说明，避免自动生成的文档缺少描述。 - 在
serializers.py里使用help_text提供字段说明，提升可读性。 - 使用
@extend_schema_view统一管理ViewSet的文档信息，减少重复代码。 - 使用
OpenApiParameter明确查询参数，提升 API 交互性。 - 提供
examples示例，让前端更容易理解 API 请求结构。
这样可以确保 API 文档清晰、可维护，方便前后端协作 。