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

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

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

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

Answer 1

ModelSerializers 是搭配 DR-Swagger 的正确方式。虽然要准确追踪从何处提取不同的 Swagger 字段可能有点棘手，但我经常不得不回退到页面呈现过程中的逐步调试，以便弄清楚事情是从哪里来的。

反过来:

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

在新式DRF序列化中，描述文本来自于ViewSet的docstring。如果您想要特定于方法的文档，则需要覆盖各个方法的文档字符串，例如检索:

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，它(虽然已弃用)具有更多功能，并且根据我的经验，序列化更可靠。