福州建设工程协会网站查询系统企业seo网站营销推广

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, 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

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)

📌 规则

1. @extend_schema(summary="简要说明", description="详细描述") 用于丰富 API 文档。
2. responses={200: UserSerializer(many=True)} 确保文档显示正确的返回格式。

---

三、在 serializers.py 里优化文档

（一）使用 help_text 和 verbose_name 提供字段说明

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"]

📌 规则

1. help_text：用于 API 文档中展示字段说明。
2. 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

📌 规则

1. @extend_schema_view 统一管理 ViewSet 方法的文档信息，避免重复写 @extend_schema。
2. 适用于 ModelViewSet。

---

五、给请求参数提供明确说明

（一）在 serializers.py 里定义 API 请求体

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 里使用

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)

📌 规则

1. request=UserCreateSerializer 指定 API 需要的请求参数格式。
2. 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)

📌 规则

1. OpenApiParameter 用于 API 查询参数说明。
2. 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"

---

总结

1. drf-spectacular 是 Django DRF 生成 OpenAPI 文档的最佳选择。
2. 使用 @extend_schema 为 API 方法添加详细说明，避免自动生成的文档缺少描述。
3. 在 serializers.py 里使用 help_text 提供字段说明，提升可读性。
4. 使用 @extend_schema_view 统一管理 ViewSet 的文档信息，减少重复代码。
5. 使用 OpenApiParameter 明确查询参数，提升 API 交互性。
6. 提供 examples 示例，让前端更容易理解 API 请求结构。

这样可以确保 API 文档清晰、可维护，方便前后端协作 🚀。