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

I've been going off of the documentation on the django-rest-swagger github page, more specifically the part called "How it works". It shows that you can define your own parameters for your rest api, and have those parameters show up in your swagger doc page.

我一直在关于django-rest-swagger github页面上的文档，更具体地说是关于它如何工作的部分。它表明您可以为其余api定义自己的参数，并在swagger文档页面中显示这些参数。

The commenting example is something like:

评论示例如下：

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

I can get this to work, but my issue is how to specify if the variable is required, its parameter type, and its data type. The github page shows an example image of how your swagger doc could look, and they have the information I just mentioned. But when I comment my custom parameters like the example shows, my parameters just show as parameter type: "query", data type: is blank, and it doesn't show "required".

我可以让它工作，但我的问题是如何指定变量是否是必需的，它的参数类型和它的数据类型。 github页面显示了你的swagger doc看起来如何的示例图像，并且它们具有我刚刚提到的信息。但是当我评论我的自定义参数时，如示例所示，我的参数只显示为参数类型：“查询”，数据类型：为空，并且不显示“必需”。

The closest thing I have found to an answer was in this * question. It seems like an answer provider is saying that django-rest-swagger generates its documentation by automatically inspecting your serializers (which is fine), and that modelserializers won't contain enough information for django-rest-swagger to properly derive the criteria I mentioned above. I get that it can't figure out this criteria but there must be some way for me to manually specify it then.

我找到答案的最接近的事情就是这个*问题。似乎答案提供者说django-rest-swagger通过自动检查你的序列化器来生成它的文档（这很好），并且模型序列化器不会包含足够的信息让django-rest-swagger正确地得出我提到的标准以上。我知道它无法弄清楚这个标准但是必须有一些方法让我手动指定它。

Am I correct that django-rest-swagger would only display what I want if I rewrote my modelserializers as just serializers? Is there no way for me to manually tell django-rest-swagger what a parameter's parameter type and data type should be, and if it's required?

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

I know I must be missing something here. I use class-based views and modelserializers that are almost identical to the examples in the django-rest-framework tutorials. It seems entirely possible that I'm just missing an understanding of "parameter types" in this context. My API is working great and I don't want to rewrite my modelserializers to serializers just so I can get better automatic documentation through swagger.

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

3 个解决方案

#1

ModelSerializers are the right way to go with DR-Swagger. It can be a bit tricky chasing down exactly where the different Swagger fields are extracted from though, I often had to fall back to step-debugging through the page rendering process in order to figure out where things were coming from.

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

In turn:

反过来：

Required? comes from the Field.required parameter (either set on the model or the Serializer field). Description comes from the Field.help_text parameter.

需要？来自Field.required参数（在模型或Serializer字段中设置）。描述来自Field.help_text参数。

In the new-style DRF serialization, the description text comes from the ViewSet's docstring. If you want method-specific docs, you need to override the docstring for individual methods, e.g. retrieve:

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

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

One thing to note is that DR-Swagger migrated to using the new DRF schema logic in version 2.0 (with DRF version 3.5), which has a few rough edges still. I recommend sticking with DR-Swagger version 0.3.x, which (though deprecated) has more features and in my experience, more reliable serialization.

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

#2

In most cases ModelSerializer is what you need, because it can be greatly customized to suit your needs. In ideal situation you should define all your constraints, like required attribute on a field, in your model class, but there are times when it's not architecturally possible, then you can override such a field in your ModelSerializer subclass:

在大多数情况下，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()

In the example above I serialize standard User model from Django and override required attributes so, that first_name and last_name are now required.

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

Of course, there are cases when it's hard or impossible to use ModelSerializer then you can always fallback to Serializer subclassing

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

#3

In the code you have:

在你的代码中：

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

msgstr“”“此文本是此API参数的描述 - 第一个参数param2 - 第二个参数”“”

Try:

尝试：

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

msgstr“”“此文本是此API参数的描述 - 第一个参数param2 - 第二个参数”“”

I have found some python and/or Django plugins need the docstring's first line, which is the one with the opening three double-quotes to also be the line that starts the documentation. You might even want to try no space between the last double-quote and the T.

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