Django DRF API 编写规范（包含 OpenAPI 生成规则）
为了确保 Django DRF API 代码的可维护性、可扩展性，同时生成清晰、规范、结构层次分明的 OpenAPI 文档，必须遵循以下规则。
一、使用 drf-spectacular 生成 OpenAPI 文档
（一）安装 drf-spectacular
pip install drf-spectacular
（二）配置 settings.py
python">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 路由
python">from drf_spectacular.views import SpectacularAPIView, SpectacularSwaggerView, SpectacularRedocViewurlpatterns = [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
python">from drf_spectacular.utils import extend_schema
from rest_framework.viewsets import ModelViewSet
from .models import User
from .serializers import UserSerializerclass 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 提供字段说明
python">from rest_framework import serializers
from .models import Userclass UserSerializer(serializers.ModelSerializer):username = serializers.CharField(help_text="用户名，唯一标识")email = serializers.EmailField(help_text="用户的电子邮箱地址")class Meta:model = Userfields = ["id", "username", "email"]
📌 规则
help_text：用于 API 文档中展示字段说明。verbose_name：如果模型里定义了，会自动生成为字段的描述。
四、使用 @extend_schema_view 让 ViewSet 更清晰
如果 ViewSet 里的方法较多，每个方法都写 @extend_schema 会很冗余，可以直接给整个 ViewSet 统一定义：
python">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 请求体
python">from drf_spectacular.utils import OpenApiExample, extend_schema
from rest_framework import serializersclass 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 里使用
python">from drf_spectacular.utils import extend_schema@extend_schema(request=UserCreateSerializer,responses={201: UserSerializer},examples=[OpenApiExample(name="示例用户",value={"username": "john_doe", "email": "john@example.com", "password": "securepassword"},request_only=True)]
)
def create(self, request, *args, **kwargs):return super().create(request, *args, **kwargs)
📌 规则
request=UserCreateSerializer指定 API 需要的请求参数格式。examples提供示例数据，方便前端查看。
六、使用 OpenApiParameter 定义查询参数
（一）示例
python">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: usernamein: querydescription: "按照用户名筛选"required: falseschema:type: string- name: pagein: querydescription: "分页参数，默认为1"required: falseschema:type: integerresponses:"200":description: "成功获取用户列表"content:application/json:schema:type: arrayitems:$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 文档清晰、可维护，方便前后端协作 🚀。
