在Django REST Framework Viewset中为drf_yasg Swagger添加请求体过滤参数

前提说明 #

你的过滤逻辑已在college_list_service中实现，以下仅针对Swagger文档的参数展示进行配置。

实现步骤 #

1. 导入必要模块

确保已安装drf-yasg，并在代码中导入相关类：

from drf_yasg import openapi
from drf_yasg.utils import swagger_auto_schema
from rest_framework import status, viewsets

2. 配置Swagger参数

根据接口请求方式选择对应配置：

情况1：GET请求（查询参数传递过滤条件）

GET接口的过滤参数通常放在URL查询串中，定义openapi.Parameter并通过manual_parameters传入装饰器：

# 定义日期参数
start_date_param = openapi.Parameter(
    name='start_date',
    in_=openapi.IN_QUERY,
    description='起始日期（格式：YYYY-MM-DD）',
    type=openapi.TYPE_STRING,
    format=openapi.FORMAT_DATE
)

end_date_param = openapi.Parameter(
    name='end_date',
    in_=openapi.IN_QUERY,
    description='结束日期（格式：YYYY-MM-DD）',
    type=openapi.TYPE_STRING,
    format=openapi.FORMAT_DATE
)

情况2：POST请求（请求体传递过滤条件）

如果list接口为POST方式，定义请求体Schema并通过request_body传入装饰器：

# 定义请求体Schema
date_filter_schema = openapi.Schema(
    type=openapi.TYPE_OBJECT,
    properties={
        'start_date': openapi.Schema(
            type=openapi.TYPE_STRING,
            format=openapi.FORMAT_DATE,
            description='起始日期（格式：YYYY-MM-DD）'
        ),
        'end_date': openapi.Schema(
            type=openapi.TYPE_STRING,
            format=openapi.FORMAT_DATE,
            description='结束日期（格式：YYYY-MM-DD）'
        )
    },
    required=['start_date', 'end_date']  # 若参数必填则添加此行
)

3. 修改ViewSet的list方法装饰器

将配置好的参数添加到@swagger_auto_schema中：

GET请求版本：

class SchoolManagementView(viewsets.ViewSet):
    def __init__(self, *args, **kwargs):
        super().__init__(**kwargs)
        self.payload = {}
        self.college_list_service = CollegeListService(view=self)

    @swagger_auto_schema(
        operation_description="Listing Inward Document",
        responses={status.HTTP_200_OK: "Success"},
        manual_parameters=[start_date_param, end_date_param]  # 新增参数配置
    )
    def list(self, request, *args, **kwargs):
        self.payload = self.college_list_service.execute(request)
        return ResponseHandler.success(payload=self.payload)

POST请求版本：

class SchoolManagementView(viewsets.ViewSet):
    def __init__(self, *args, **kwargs):
        super().__init__(**kwargs)
        self.payload = {}
        self.college_list_service = CollegeListService(view=self)

    @swagger_auto_schema(
        operation_description="Listing Inward Document",
        responses={status.HTTP_200_OK: "Success"},
        request_body=date_filter_schema  # 新增请求体配置
    )
    def list(self, request, *args, **kwargs):
        self.payload = self.college_list_service.execute(request)
        return ResponseHandler.success(payload=self.payload)

注意事项 #

• 若参数为可选，定义时不要添加required配置
• 确保college_list_service已正确处理request.query_params（GET）或request.data（POST）中的start_date和end_date参数

内容的提问来源于stack exchange，提问作者Abbas Shaikh