总结：在 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 Responseclass 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 = CustomUserSerializerpermission_classes = [AllowAny]
（三）自定义请求参数、响应格式和示例
1. 自定义查询参数
可以使用 OpenApiParameter 定义查询参数，并为其添加说明。
from drf_spectacular.utils import OpenApiParameterclass 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 OpenApiExampleclass 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 OpenApiResponseclass 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"})
（五）总结
| 功能 | 方法 | 适用场景 |
|---|---|---|
| 修改 API 标题、描述等信息 | 在 settings.py 中配置 SPECTACULAR_SETTINGS | 设置全局的 API 信息（如标题、版本、描述、许可证等） |
| 修改单个视图注释 | 使用 @extend_schema 修饰视图方法 | 为单个视图或端点添加 summary、description 和 tags |
| 修改多个视图注释 | 使用 @extend_schema_view 修饰 ViewSet 或多个方法 | 为多个视图方法批量修改 API 注释 |
| 自定义请求参数 | 使用 OpenApiParameter 添加查询参数 | 添加查询参数，如 q 或 page |
| 自定义请求体 | 使用 OpenApiExample 定义请求体和示例 | 定义 POST 请求的请求体数据结构及示例 |
| 自定义响应格式 | 使用 OpenApiResponse 定义响应格式、状态码及返回数据结构 | 自定义响应数据结构和返回状态码 |
| 隐藏 API 端点 | 使用 @extend_schema(exclude=True) 隐藏某个端点 | 隐藏某些 API 端点，避免它们出现在生成的文档中 |
通过这些方法，您可以精确控制 drf-spectacular 生成的 OpenAPI 文档，使其符合您的需求并提升 API 可读性。
