【后端】【django-drf】【drf-spectacular】总结：在 drf-spectacular 中添加 API 注释的方法

总结：在 drf-spectacular 中添加 API 注释的方法

在 drf-spectacular 中，可以通过几种不同的方式来添加 API 注释（如 summary、tags、description 等），以生成更具描述性的 OpenAPI 文档。

（一）全局配置：修改 API 的标题、描述等信息

可以在 settings.py 中使用 SPECTACULAR_SETTINGS 配置全局的 API 信息，如 API 名称、描述、版本等。

SPECTACULAR_SETTINGS = {
    'TITLE': "My API",  # API 标题
    'DESCRIPTION': "这是 API 文档的描述信息",  # API 描述
    'VERSION': "v1.0",  # API 版本
    'CONTACT': {
        'name': "API Support",
        'email': "support@example.com",
        'url': "https://www.example.com/support",
    },
    'LICENSE': {
        'name': "MIT License",
        'url': "https://opensource.org/licenses/MIT",
    },
    'TOS': "https://www.example.com/terms/",
}

（二）在视图中添加注释：使用 @extend_schema 和 @extend_schema_view

1. 使用 @extend_schema 添加单个视图的注释

可以通过 @extend_schema 修饰单个视图方法，添加 summary、description、tags 等注释信息。

from drf_spectacular.utils import extend_schema
from rest_framework.views import APIView
from rest_framework.response import Response

class MyAPIView(APIView):
    @extend_schema(
        summary="获取用户信息",  # API 简短描述
        description="此端点用于获取用户的详细信息",  # API 详细描述
        tags=["用户管理"],  # API 分类标签
    )
    def get(self, request):
        return Response({"name": "Tom"})

2. 使用 @extend_schema_view 添加视图集的注释

如果要批量修改一个 ViewSet 中的多个方法注释，可以使用 @extend_schema_view。

from drf_spectacular.utils import extend_schema_view, extend_schema

@extend_schema_view(
    list=extend_schema(summary="获取用户列表", tags=["用户管理"]),
    create=extend_schema(summary="创建新用户", tags=["用户管理"]),
)
class CustomUserViewSet(viewsets.ModelViewSet):
    queryset = CustomUser.objects.all()
    serializer_class = CustomUserSerializer
    permission_classes = [AllowAny]

（三）自定义请求参数、响应格式和示例

1. 自定义查询参数

可以使用 OpenApiParameter 定义查询参数，并为其添加说明。

from drf_spectacular.utils import OpenApiParameter

class UserSearchView(APIView):
    @extend_schema(
        parameters=[
            OpenApiParameter(name="q", type=str, description="搜索关键字"),
            OpenApiParameter(name="page", type=int, description="分页页码", default=1),
        ],
        summary="搜索用户",
        tags=["用户管理"],
    )
    def get(self, request):
        return Response({"results": []})

2. 自定义请求体

可以为 POST 请求自定义 request body，指定数据结构和示例。

from drf_spectacular.utils import OpenApiExample

class UserCreateView(APIView):
    @extend_schema(
        request={
            "application/json": {
                "type": "object",
                "properties": {
                    "username": {"type": "string", "example": "Tom"},
                    "email": {"type": "string", "example": "tom@example.com"},
                },
            }
        },
        examples=[
            OpenApiExample(
                "示例请求",
                summary="示例 1",
                value={"username": "Tom", "email": "tom@example.com"},
            )
        ],
        summary="创建用户",
        tags=["用户管理"],
    )
    def post(self, request):
        return Response({"message": "User created"})

3. 自定义响应格式

可以指定响应的格式、状态码和返回的数据结构。

from drf_spectacular.utils import OpenApiResponse

class UserDetailView(APIView):
    @extend_schema(
        responses={
            200: OpenApiResponse(response=UserSerializer, description="成功返回用户详情"),
            400: OpenApiResponse(description="请求参数错误"),
        },
        summary="获取用户详情",
        tags=["用户管理"],
    )
    def get(self, request):
        return Response({"username": "Tom", "email": "tom@example.com"})

（四）隐藏 API 端点

如果你希望某个 API 端点不出现在文档中，可以使用 exclude=True 隐藏该 API。

from drf_spectacular.utils import extend_schema

@extend_schema(exclude=True)
class HiddenView(APIView):
    def get(self, request):
        return Response({"message": "This API is hidden"})

（五）总结

通过这些方法，您可以精确控制 drf-spectacular 生成的 OpenAPI 文档，使其符合您的需求并提升 API 可读性。