如何在Django REST Framework中显示查询参数选项 - Swagger

This has been bugging me for a while now.

这一直困扰着我一段时间。

My ultimate goal is to show query parameter options inside SwaggerUI and give a form input for each query parameter. Similar to how it is displayed when providing a serializer for POST.

我的最终目标是在SwaggerUI中显示查询参数选项，并为每个查询参数提供表单输入。与为POST提供序列化程序时的显示方式类似。

I am using a viewset which inherits from GenericViewSet and I have tried the following:

我正在使用一个继承自GenericViewSet的视图集，我尝试了以下内容：

provide filter_fields attribute
提供filter_fields属性
provide and set filter_backends attribute to (filters.DjangoFilterBackend,)
提供并设置filter_backends属性为（filters.DjangoFilterBackend，）
provide filter_class defined inside my module.
提供我的模块中定义的filter_class。
Override options method to provide [actions][GET] information
覆盖选项方法以提供[actions] [GET]信息

Here's a small catch, I am not using any models so I don't think DjangoFilterBackend will really help me. I am using DjangoRESTFramework to talk to an outside API, and I am simply getting JSON result back, and passing it through to the frontend layer.

这是一个小问题，我没有使用任何模型，所以我不认为DjangoFilterBackend会真的帮助我。我正在使用DjangoRESTFramework与外部API进行通信，我只是简单地获取JSON结果，并将其传递给前端层。

Here is a small modified snippet of my code to better explain my problem:

这是我的代码的一个小修改片段，以更好地解释我的问题：

views.py

class SomeViewSet(GenericViewSet):
    # Note that I have all of these defined, but I have tried various combinations
    filter_fields = ('query_option_1', 'query_option_2',)
    filter_backeds = (filters.DjangoFilterBackend,)
    filter_class = SomeFilter
    query_metadata = some_dict

    # This works when request is OPTIONS
    def options(self, request, *args, **kwargs):
        if self.metadata_class is None:
            return self.http_method_not_allowed(request, *args, **kwargs)
        data = self.metadata_class().determine_metadata(request, self)
        data['actions']['GET'] = self.query_metadata
        return Response(data, status=status.HTTP_200_OK)

filters.py

class SomeFilter(FilterSet):
    strict = True
    query_option_1 = django_filters.NumberFilter(name='query_option_1')
    query_option_2 = django_filters.NumberFilter(name='query_option_2')

    class Meta:
        fields = ['query_option_1', 'query_option_2']

Thank you for looking, and thanks in advance for responding.

感谢您的关注，并提前感谢您的回复。

3 个解决方案

#1

New swagger

新招摇

class SimpleFilterBackend(BaseFilterBackend):
    def get_schema_fields(self, view):
        return [coreapi.Field(
            name='query',
            location='query',
            required=False,
            type='string'
        )]

class MyViewSet(viewsets.ViewSet):
    filter_backends = (SimpleFilterBackend,)

    def list(self, request, *args, **kwargs):
        return Response({'hello': 'world'}, status.HTTP_200_OK)

#2

Okay, for those who stumble upon this question, I have figured it out. It is rather silly, and I feel a little stupid for not knowing, but in my defense, it was not clearly documented. The information was not found in DRF documentation, or inside Django REST Swagger repository. Instead it was found under django-rest-framework-docs, which is what Django REST Swagger is built off of.

好吧，对于那些偶然发现这个问题的人，我已经弄明白了。这是相当愚蠢的，我觉得不知道有点愚蠢，但在我的辩护中，没有明确记录。在DRF文档或Django REST Swagger存储库中找不到该信息。相反，它是在django-rest-framework-docs下找到的，这就是Django REST Swagger的基础。

To specify your query parameter to show up in your SwaggerUI as a form field, you simply comment like so:

要指定您的查询参数作为表单字段显示在SwaggerUI中，您只需这样注释：

def list(self):
    """
    param1 -- A first parameter
    param2 -- A second parameter
    """ 
    ...

And swagger will parse your comments and will put a form input for param1 and param2. What follows -- are the descriptions for the parameters.

并且swagger将解析您的注释，并将为param1和param2输入表单。接下来是 - 参数的描述。

#3

I found the rest framework swagger docs. so we can write the parameter type(interger, char), response, etc.

我找到了其余的框架swagger docs。所以我们可以编写参数类型（整数，字符），响应等。

the tripple --- is necessary.

tripple ---是必要的。

@api_view(["POST"])
def foo_view(request):
    """
    Your docs
    ---
    # YAML (must be separated by `---`)

    type:
      name:
        required: true
        type: string
      url:
        required: false
        type: url
      created_at:
        required: true
        type: string
        format: date-time

    serializer: .serializers.FooSerializer
    omit_serializer: false

    parameters_strategy: merge
    omit_parameters:
        - path
    parameters:
        - name: name
          description: Foobar long description goes here
          required: true
          type: string
          paramType: form
        - name: other_foo
          paramType: query
        - name: other_bar
          paramType: query
        - name: avatar
          type: file

    responseMessages:
        - code: 401
          message: Not authenticated
    """

How about the situation we use the mixins class such as ModelViewSets. Do we need to define the list function just to add the docs? -- No

我们使用mixins类的情况怎么样，比如ModelViewSets。我们是否需要定义列表函数才能添加文档？ - 不

We can do like this:

我们可以这样做：

class ArticleViewSet(viewsets.ModelViewSet):

    """
    Articles.
    ---
    list:    #<--- here!!
        parameters:
            - name: name
              description: article title
    get_price:
        omit_serializer: true

    """

    @list_route(methods=['get'])
    def get_price(self, request):
        pass

#1