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

Posted 2023-02-23

【中文标题】django-rest-swagger 是不是不适用于模型序列化器？

【英文标题】：Does django-rest-swagger not work well with modelserializers?django-rest-swagger 是否不适用于模型序列化器？

【发布时间】：2014-08-11 10:12:01

【问题描述】：

我已经离开了 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 页面显示了一个example image，说明了你的 swagger 文档的外观，他们有我刚才提到的信息。但是当我像示例显示的那样评论我的自定义参数时，我的参数只显示为参数类型：“查询”，数据类型：为空白，并且不显示“必需”。

我找到的最接近答案的是this *** question。似乎答案提供者在说 django-rest-swagger 通过自动检查您的序列化程序（这很好）来生成其文档，并且模型序列化程序不会包含足够的信息，以便 django-rest-swagger 正确得出我提到的标准更多。我知道它无法确定这个标准，但我必须有某种方法可以手动指定它。

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

我知道我一定在这里遗漏了一些东西。我使用与 django-rest-framework 教程中的示例几乎相同的基于类的视图和模型序列化器。在这种情况下，我完全有可能只是缺少对“参数类型”的理解。我的 API 运行良好，我不想将我的模型序列化器重写为序列化器，这样我就可以通过 swagger 获得更好的自动文档。

【问题讨论】：

鉴于您显然已经有一些时间尝试深入研究这个问题，因此在 Django REST framework discussion group 上提出这个问题可能也值得 - 可能能够从那里的 Marc Gibbons 或其他人那里得到答案否则使用他的项目。

@TomChristie 谢谢你的建议

关于该主题的任何更新？我有同样的问题，如果你能分享你的经验会很棒。提前致谢！

@fox，我还没有找到任何东西。我在推荐的讨论组中发布了它，但我不记得曾经收到任何反馈。

@suark_krab 你得到答案了吗？

【参考方案1】：

ModelSerializer 是使用 DR-Swagger 的正确方法。准确地追踪提取不同 Swagger 字段的位置可能有点棘手，但我经常不得不退回到通过页面渲染过程进行逐步调试，以找出事情的来源。

反过来：

需要吗？来自 Field.required 参数（在模型或 Serializer 字段上设置）。 说明来自 Field.help_text 参数。

在新型 DRF 序列化中，描述文本来自 ViewSet 的文档字符串。如果您想要特定于方法的文档，则需要覆盖各个方法的文档字符串，例如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，它（尽管已弃用）具有更多功能，并且根据我的经验，更可靠的序列化。

【讨论】：

如果您想要更短的方法，也可以使用MySerializer.retreive.__func__.__doc__ = "Retrieve a FooBar"。

【参考方案2】：

在大多数情况下，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 子类化

【参考方案3】：

在您拥有的代码中：

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

试试：

""" 此文本是此 API 的描述 param1 -- 第一个参数 param2 -- 第二个参数 """

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