【后端】【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)

📌 规则

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 User

class UserSerializer(serializers.ModelSerializer):
    username = serializers.CharField(help_text="用户名，唯一标识")
    email = serializers.EmailField(help_text="用户的电子邮箱地址")

    class Meta:
        model = User
        fields = ["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 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": "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: 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"

总结

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 文档清晰、可维护，方便前后端协作 🚀。