如何在drf-yasg的Swagger UI中显示PATCH接口的pk字段？

我使用drf-yasg、jwt和Django REST Framework开发项目，代码托管在GitHub仓库。尝试配置PATCH方法实现任务编辑功能时，发现Swagger UI中未显示pk字段，仅能看到请求体示例，截图如下：

核心代码如下：

def get_payload(request):
    token = request.COOKIES.get('jwt')
    if not token:
        raise AuthenticationFailed('Unauthenticated!')

    try:
        payload = jwt.decode(token, 'secret', algorithms=['HS256'])
    except jwt.ExpiredSignatureError:
        raise AuthenticationFailed('Unauthenticated!')
    return payload


class TaskView(APIView):
    pk = openapi.Parameter('pk', openapi.IN_QUERY,
                             description="field you want to order by to",
                             type=openapi.TYPE_INTEGER)
    @swagger_auto_schema(
        request_body=openapi.Schema(
            manual_parameters=[pk],
            type=openapi.TYPE_OBJECT,
            properties={
                'taskname': openapi.Schema(type=openapi.TYPE_STRING, description='Add taskname'),
                'completion': openapi.Schema(type=openapi.TYPE_BOOLEAN, description='completion'),
            }
        )
    )
    def patch(self, request, pk):
        payload = get_payload(request=request)
        task = Tasks.objects.filter(id=pk, username=payload['username']).first()
        serializer = TaskSerializer(task, data=request.data)
        if serializer.is_valid():
            serializer.save()
            return Response(serializer.data)
        return Response(serializer.errors, status=status.HTTP_400_BAD_REQUEST)  

问题根源有两个：

1. 错误地将manual_parameters嵌套在request_body配置中，它应该是@swagger_auto_schema的直接参数。
2. pk是URL路径参数（对应patch方法的入参），但你定义成了查询参数（openapi.IN_QUERY），应改为openapi.IN_PATH。

修改后的代码：

def get_payload(request):
    token = request.COOKIES.get('jwt')
    if not token:
        raise AuthenticationFailed('Unauthenticated!')

    try:
        payload = jwt.decode(token, 'secret', algorithms=['HS256'])
    except jwt.ExpiredSignatureError:
        raise AuthenticationFailed('Unauthenticated!')
    return payload


class TaskView(APIView):
    @swagger_auto_schema(
        # 将manual_parameters提升为swagger_auto_schema的直接参数
        manual_parameters=[
            openapi.Parameter(
                name='pk',
                in_=openapi.IN_PATH,
                description='需要编辑的任务ID',
                type=openapi.TYPE_INTEGER,
                required=True
            )
        ],
        request_body=openapi.Schema(
            type=openapi.TYPE_OBJECT,
            properties={
                'taskname': openapi.Schema(type=openapi.TYPE_STRING, description='任务名称'),
                'completion': openapi.Schema(type=openapi.TYPE_BOOLEAN, description='任务完成状态'),
            }
        )
    )
    def patch(self, request, pk):
        payload = get_payload(request=request)
        task = Tasks.objects.filter(id=pk, username=payload['username']).first()
        serializer = TaskSerializer(task, data=request.data)
        if serializer.is_valid():
            serializer.save()
            return Response(serializer.data)
        return Response(serializer.errors, status=status.HTTP_400_BAD_REQUEST)  

额外优化建议：

• 如果你的URL路由配置为path('tasks/<int:pk>/', TaskView.as_view())这种路径参数形式，drf-yasg可以自动识别pk字段，无需手动配置manual_parameters，可以直接删除这部分配置进行测试。
• 将描述文字改为贴合业务的内容，提升文档可读性。

内容的提问来源于stack exchange，提问作者Echchama Nayak