django-filters中OrderingFilter的field_labels在Swagger中不生效问题

我定义了如下模型、FilterSet类及视图：

模型代码 #

class Calendar(models.Model):
    ...
    vendor_code = models.TextField()
    ...

FilterSet类代码 #

from django_filters import OrderingFilter
from django_filters.rest_framework import FilterSet, DjangoFilterBackend

class CalendarFilter(FilterSet):

    ordering = OrderingFilter(
        fields=(
            ('vendor_code', 'vendor_code'),
        ),
        field_labels={
            'vendor_code': 'Vendor code',
        }
    )

    class Meta:
        model = Calendar
        fields = ['vendor_code']

视图代码 #

class CalendarsView(mixins.ListModelMixin, GenericViewSet):
    ...
    filter_backends = (DjangoFilterBackend,)
    filterset_class = CalendarFilter

我预期Swagger中会显示设置的“Vendor code”标签，但实际仅显示“ordering”且无描述，前端开发者无法看到该标签。请问哪里操作有误？

问题核心是OrderingFilter的field_labels配置不会被Swagger自动识别，默认的ordering参数只会显示参数名，不会展开对应的排序选项标签。以下是几种可行的解决方式：

• 直接添加help_text说明
  在OrderingFilter定义里补充help_text，把排序字段对应的标签明确写出来，Swagger会直接显示这段帮助文本：

  ordering = OrderingFilter(
      fields=(
          ('vendor_code', 'vendor_code'),
      ),
      field_labels={
          'vendor_code': 'Vendor code',
      },
      help_text="排序选项：vendor_code（Vendor code 升序），-vendor_code（Vendor code 降序）"
  )
  

• 用Swagger工具的自定义参数配置（以drf-yasg为例）
  如果项目用drf-yasg生成文档，可通过swagger_auto_schema手动定义排序参数的描述和可选值：

  from drf_yasg.utils import swagger_auto_schema
  from drf_yasg import openapi
  
  class CalendarsView(mixins.ListModelMixin, GenericViewSet):
      ...
      filter_backends = (DjangoFilterBackend,)
      filterset_class = CalendarFilter
  
      @swagger_auto_schema(
          manual_parameters=[
              openapi.Parameter(
                  name='ordering',
                  in_=openapi.IN_QUERY,
                  description="排序字段：输入 vendor_code 按Vendor code升序，输入 -vendor_code 按Vendor code降序",
                  type=openapi.TYPE_STRING,
                  enum=['vendor_code', '-vendor_code']
              )
          ]
      )
      def list(self, request, *args, **kwargs):
          return super().list(request, *args, **kwargs)
  

• 检查插件兼容性（针对drf-spectacular）
  如果用drf-spectacular，需要在settings.py中开启django-filter支持，确保配置正确：

  SPECTACULAR_SETTINGS = {
      'COMPONENT_SPLIT_REQUEST': True,
      'ENABLE_DJANGO_FILTER': True,
  }
  

另外注意：FilterSet元类里的fields = ['vendor_code']是用于过滤的配置，和排序的OrderingFilter是独立模块，两者互不影响。

内容的提问来源于stack exchange，提问作者Альберт Александров