django-rest-swagger不能很好地与模型序列化程序一起工作吗？

Question

我已经离开了django-rest-swagger github page的文档，更确切地说是“它是如何工作的”这一部分。它表明您可以为rest api定义自己的参数，并让这些参数显示在您的swagger文档页面中。

注释示例类似于：

"""    
This text is the description for this API    
param1 -- A first parameter    
param2 -- A second parameter    
"""    

我可以让它工作，但我的问题是如何指定变量是否是必需的、它的参数类型和它的数据类型。github页面显示了你的swagger文档的example image，它们包含了我刚才提到的信息。但是，当我像示例一样注释我的自定义参数时，我的参数只显示为参数类型："query"，data type:为空，而不显示"required“。

我找到的最接近答案的东西是this stackoverflow question。看起来答案提供商说django-rest-swagger是通过自动检查序列化程序来生成文档的(这很好)，而模型序列化程序不会包含足够的信息让django-rest-swagger正确地推导出我上面提到的条件。我知道它不能计算出这个标准，但一定有办法让我手动指定它。

如果我将我的模型序列化程序重写为仅仅是序列化程序，那么django-rest-swagger只会显示我想要的东西，这是正确的吗？有没有办法让我手动告诉django-rest-swagger一个参数的参数类型和数据类型应该是什么，以及它是否是必需的？

我知道我一定漏掉了什么。我使用的基于类的视图和模型序列化程序与django-rest-framework教程中的示例几乎相同。在这种情况下，我似乎完全有可能缺少对“参数类型”的理解。我的API工作得很好，我不想把我的模型序列化程序重写成序列化程序，这样我就可以通过swagger获得更好的自动化文档。

Answer 1

ModelSerializers是DR-Swagger的正确选择。追查不同的Swagger字段是从哪里提取出来的可能有点棘手，但我经常不得不退回到页面渲染过程中的单步调试，以便找出东西是从哪里来的。

依次为：

必需的？来自Field.required参数(在模型或序列化程序字段上设置)。描述来自Field.help_text参数。

在新型DRF序列化中，描述文本来自ViewSet的docstring。如果需要特定于方法的文档，则需要覆盖单个方法的文档字符串，例如retrieve

def retrieve(self, request, *args, **kwargs):
    """Retrieve a FooBar"""
    return super().retrieve(request, *args, **kwargs)

要注意的一件事是，DR-Swagger迁移到使用2.0版(使用DRF 3.5版)中的新DRF模式逻辑，它仍然有一些粗糙的边缘。我建议继续使用DR-Swagger版本0.3.x，它(虽然已被弃用)具有更多功能，并且在我的经验中，序列化更可靠。

Answer 2

在大多数情况下，ModelSerializer是您所需要的，因为它可以进行大量定制以满足您的需求。在理想情况下，您应该在模型类中定义所有约束，例如字段上的必需属性，但有时在体系结构上不可行，那么您可以在ModelSerializer子类中覆盖这样的字段：

from django.contrib.auth import get_user_model
from rest_framework import serializers


class UserSerializer(serializers.ModelSerializer):
    first_name = serializers.CharField(required=True)
    last_name = serializers.CharField(required=True)

    class Meta:
        model = get_user_model()

在上面的示例中，我序列化了Django中的标准用户模型，并覆盖了所需的属性，因此，现在需要first_name和last_name。

当然，在某些情况下，很难或不可能使用ModelSerializer，那么您总是可以退回到序列化器子类化

Answer 3

在您拥有的代码中：

""“

此文本是对此接口的描述

param1 --第一个参数

param2 --第二个参数

""“

尝试：

“此文本是对此接口的描述

param1 --第一个参数

param2 --第二个参数

""“

我发现一些python和/或Django插件需要docstring的第一行，也就是开头三个双引号的那一行，也是文档的开头行。您甚至可以尝试在最后一个双引号和T之间不留空格。