django-rest-swagger不适用于模型序列化器吗?

时间:2014-06-20 15:34:19

标签: python django rest django-rest-framework swagger

我已经离开了关于django-rest-swagger github page的文档,更具体地说是关于"它是如何工作的部分"。它表明您可以为其余api定义自己的参数,并将这些参数显示在您的swagger文档页面中。

评论示例如下:

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

我可以让它工作,但我的问题是如何指定变量是否是必需的,它的参数类型和它的数据类型。 github页面显示了example image你的招摇文档的外观,并且他们有我刚才提到的信息。但是当我评论我的自定义参数时,例如显示,我的参数只显示为参数类型:"查询",数据类型:是空白,并且它没有显示" required&#34 ;。

我找到答案的最接近的事情是this stackoverflow question。似乎答案提供者说django-rest-swagger通过自动检查序列化器来生成其文档(这很好),并且模型序列化器不会包含足够的信息,以便django-rest-swagger正确地推导出标准我上面提到过。我知道它无法弄清楚这个标准,但我必须有一些方法可以手动指定它。

我是否正确django-rest-swagger只会显示我想要的内容,如果我将我的模型序列化器重写为序列化器?有没有办法让我手动告诉django-rest-swagger参数的参数类型和数据类型应该是什么,以及是否需要它?

我知道我必须在这里遗漏一些东西。我使用基于类的视图和模型序列化器,它们几乎与django-rest-framework教程中的示例相同。我完全有可能错过了对参数类型的理解"在这种背景下。我的API运行良好,我不想将我的模型序列化器重写为序列化器,因此我可以通过招摇获得更好的自动文档。

3 个答案:

答案 0 :(得分:2)

ModelSerializers是使用DR-Swagger的正确方法。尽管可能有点棘手地追逐不同的Swagger字段,但我经常不得不通过页面渲染过程回退到步骤调试,以便弄清楚事物的来源。

反过来:

必需?来自Field.required参数(在模型或Serializer字段中设置)。 描述来自Field.help_text参数。

在新式DRF序列化中,描述文本来自ViewSet的文档字符串。如果您需要特定于方法的文档,则需要覆盖单个方法的文档字符串,例如sql query

retrieve

需要注意的一点是,DR-Swagger已迁移到使用版本2.0中的新DRF架构逻辑(DRF版本为3.5),它仍有一些粗糙的边缘。我建议坚持使用DR-Swagger版本0.3.x,虽然已弃用,但它具有更多功能,根据我的经验,更可靠的序列化。

答案 1 :(得分:1)

在大多数情况下,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 。< / p>

当然,有些情况下,使用ModelSerializer很难或不可能,那么你总是可以回退到Serializer子类化

答案 2 :(得分:0)

在你的代码中:

&#34;&#34;&#34;
本文是此API的说明 param1 - 第一个参数
param2 - 第二个参数
&#34;&#34;&#34;

尝试:

&#34;&#34;&#34;本文是此API的说明 param1 - 第一个参数
param2 - 第二个参数
&#34;&#34;&#34;

我发现一些python和/或Django插件需要docstring的第一行,这是打开三个双引号的那一行也是启动文档的行。您甚至可能希望在最后一个双引号和T之间没有空格。