drf-spectaulous：添加响应描述

Question

如何在 @extend_schema 装饰器中添加描述到响应？

'500':
  content:
    application/json:
      schema:
        $ref: '#/components/schemas/Error'
      description: ''

Answer 1

Insa 的回答和评论让我找到了一个可行的解决方案OpenApiResponse（需要 drf-spectaulous 版本 >=0.15）

这是我如何做到这一点的一些示例代码：

from drf_spectacular.utils import extend_schema, OpenApiResponse
from rest_framework import generics

class MyResourceList(generics.ListCreateAPIView):

    @extend_schema(
        summary="Create a new resource",
        responses={
            201: OpenApiResponse(response=MyCustomSerializer,
                                 description='Created. New resource in response'),
            400: OpenApiResponse(description='Bad request (something invalid)'),
        },
    )
    def post(self, request, *args, **kwargs):
        """ 
        Some explanation goes here ...
        """
        return super().post(request, *args, **kwargs)

• 有关 OpenApiResponse 的文档位于：https://drf-spectaulous.readthedocs.io/en/latest/drf_spectaulous.html ?highlight=openapiresponse#drf_spectaulous.utils.OpenApiResponse
• 但测试实际上更有用：https://github.com/tfranzel/drf-spectaulous/blob/1f7cf5d8342f5ed3f619afcf92fb43e3b4ff26cb/tests/test_regressions.py#L1744

Answer 2

您所指的具体描述位置无法通过装饰器轻松获得。然而，有多个地方可以放置描述。

1. @extend_schema(description='Your description')这会将描述添加到视图操作（操作）中。但是，这是针对操作本身而不是500错误情况。

2. 将文档字符串添加到Error序列化器中。可能是你想做的事。

这部分仍然有点粗糙，因为“错误”功能仍在进行中。