首页 文章

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

提问于
浏览 次
13

我一直在关于django-rest-swagger github page的文档，更具体地说是名为"How it works"的文档 . 它表明您可以为其余api定义自己的参数，并在swagger文档页面中显示这些参数 .

评论示例如下：

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

我可以让它工作，但我的问题是如何指定变量是否是必需的，它的参数类型和它的数据类型 . github页面显示了你的swagger文档的外观example image，并且它们有我刚才提到的信息 . 但是当我评论我的自定义参数时，如示例所示，我的参数只显示为参数类型："query"，数据类型：为空，并且它不显示"required" .

我找到答案的最接近的是this stackoverflow question . 看起来答案提供者似乎是说django-rest-swagger通过自动检查你的序列化器来生成它的文档（这很好），并且模型序列化器赢得了't contain enough information for django-rest-swagger to properly derive the criteria I mentioned above. I get that it can' t这个标准，但必须有一些方法让我手动指定它然后 .

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

我知道我必须在这里遗漏一些东西 . 我使用基于类的视图和模型序列化器，它们几乎与django-rest-framework教程中的示例相同 . 在这种情况下，我似乎完全没有理解“参数类型” . 我的API运行良好，我不想将我的模型序列化器重写为序列化器，因此我可以通过swagger获得更好的自动文档 .

python django rest django-rest-framework swagger

3 回答

  • 1

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

    反过来：

    需要？来自Field.required参数（在模型或Serializer字段中设置） . 描述来自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模式逻辑（DRF版本3.5），它仍然有一些粗糙的边缘 . 我建议坚持使用DR-Swagger版本0.3.x，虽然已弃用（虽然已弃用），但它具有更多功能，根据我的经验，更可靠的序列化 .

    回复于
  • 0

    在大多数情况下，ModelSerializer是您所需要的，因为它可以根据您的需求进行大量定制 . 在理想情况下，您应该在模型类中定义所有约束，例如字段上的 required 属性，但有时候它在架构上是不可能的，那么您可以在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序列化标准用户模型并覆盖 required 属性，因此现在需要 first_name 和 last_name .

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

    回复于
  • 2

    在你的代码中：

    “””
    此文本是此API的说明
    param1 - 第一个参数
    param2 - 第二个参数
    “””

    尝试：

    msgstr“”“此文本是此API的说明
    param1 - 第一个参数
    param2 - 第二个参数
    “””

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

    回复于

相关问题