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

Question

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.

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

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.

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?

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.

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

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.

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, eg retrieve :

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.

Answer 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:

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.

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

Answer 3

In the code you have:

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

Try:

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

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.