如何为基于drf_yasg+Redoc的Django REST Framework API文档添加查询参数

我之前也碰到过这个问题——drf_yasg不会自动识别你手动从query_params里读取的参数，得主动告诉它这些参数的存在才行。这里分享两种实用的解决方法：

方法一：手动用swagger_auto_schema装饰器声明参数 #

这种方法适合快速给单个接口添加参数说明，不需要额外依赖。

首先导入需要的模块：

from drf_yasg.utils import swagger_auto_schema
from drf_yasg import openapi

然后给你的list方法加上装饰器，手动定义每个查询参数的信息：

class TechnicalDataViewSet(viewsets.ViewSet):
    """ A simple ViewSet for listing or retrieving machine. """
    permission_classes = [permissions.IsAuthenticated]

    @swagger_auto_schema(
        manual_parameters=[
            openapi.Parameter(
                'id_machine',
                openapi.IN_QUERY,
                description="过滤指定机器ID对应的技术数据",
                type=openapi.TYPE_INTEGER,
                required=False  # 明确标注为可选参数
            ),
            openapi.Parameter(
                'name',
                openapi.IN_QUERY,
                description="按名称精确匹配过滤技术数据",
                type=openapi.TYPE_STRING,
                required=False
            )
        ]
    )
    def list(self, request):
        # 原有业务代码保持不变
        id_machine = self.request.query_params.get('id_machine')
        name = self.request.query_params.get('name')
        queryset = TechnicalData.objects.all()
        if id_machine:
            queryset = queryset.filter(machine__id=id_machine)
        if name:
            queryset = queryset.filter(name=name)
        serializer = TechnicalDataSerializer(queryset, many=True)
        return Response(serializer.data)

    # 你的retrieve方法...

重启服务后，Redoc文档里就会显示这两个可选的查询参数了。

方法二：用Django Filter自动生成参数（更推荐） #

如果你的过滤逻辑比较复杂，或者想遵循DRF的规范，用django-filter是更好的选择——它不仅能自动生成文档参数，还能帮你简化过滤逻辑的代码。

步骤1：安装并配置django-filter #

先安装依赖：

pip install django-filter

然后在settings.py里添加配置：

INSTALLED_APPS = [
    # 其他已安装的app
    'django_filters',
]

REST_FRAMEWORK = {
    # 其他配置
    'DEFAULT_FILTER_BACKENDS': ['django_filters.rest_framework.DjangoFilterBackend']
}

步骤2：创建FilterSet类 #

在你的app里创建一个filters.py（或者直接写在views文件里），定义过滤规则：

import django_filters
from .models import TechnicalData

class TechnicalDataFilter(django_filters.FilterSet):
    # 针对外键machine的id，明确指定字段映射
    id_machine = django_filters.NumberFilter(field_name='machine__id', lookup_expr='exact')
    # 名称过滤，默认是精确匹配，也可以改成icontains实现模糊搜索
    name = django_filters.CharFilter(lookup_expr='exact')

    class Meta:
        model = TechnicalData
        fields = ['id_machine', 'name']

步骤3：在ViewSet中使用FilterSet #

修改你的ViewSet，去掉手动处理query_params的代码，改用DRF的过滤机制：

from django_filters.rest_framework import DjangoFilterBackend
from .filters import TechnicalDataFilter

class TechnicalDataViewSet(viewsets.ViewSet):
    """ A simple ViewSet for listing or retrieving machine. """
    permission_classes = [permissions.IsAuthenticated]
    filter_backends = [DjangoFilterBackend]
    filterset_class = TechnicalDataFilter

    def list(self, request):
        queryset = TechnicalData.objects.all()
        # 用DRF内置方法处理过滤，无需自己写if判断
        queryset = self.filter_queryset(queryset)
        serializer = TechnicalDataSerializer(queryset, many=True)
        return Response(serializer.data)

    # 你的retrieve方法...

这样drf_yasg会自动识别FilterSet里的参数，在Redoc文档里展示每个参数的类型、描述，而且你的过滤逻辑代码也更简洁易维护。

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