问题描述

我已经离开了 django-rest-swagger github 页面上的文档，更具体地说，称为它是如何工作的"的部分.它表明您可以为您的 rest api 定义自己的参数，并将这些参数显示在您的 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.

评论的例子是这样的:

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

我可以让它工作，但我的问题是如何指定变量是否是必需的、它的参数类型和它的数据类型.github 页面显示了 示例图片你的大摇大摆的文档看起来如何，他们有我刚才提到的信息.但是当我像示例显示的那样评论我的自定义参数时，我的参数只显示为参数类型:查询"，数据类型:为空，并且不显示必需".

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".

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

The closest thing I have found to an answer was in this stackoverflow 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-framework 教程中的示例几乎相同的基于类的视图和模型序列化器.在这种情况下，我完全有可能只是缺少对参数类型"的理解.我的 API 运行良好，我不想将我的模型序列化器重写为序列化器，这样我就可以通过 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.

推荐答案

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

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.

反过来:

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

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

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

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:

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

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.

这篇关于django-rest-swagger 是否不适用于模型序列化器?的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持跟版网！