[Fixed]-Does django-rest-swagger not work well with modelserializers?

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, e.g. 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.

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

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.