Examples

Basic Example with a ViewSet

Consider the following ViewSet:

class CigarViewSet(viewsets.ModelViewSet):

    """ Cigar resource. """

    serializer_class = CigarSerializer
    model = Cigar
    queryset = Cigar.objects.all()

    def list(self, request, *args, **kwargs):
        """
        Return a list of objects.

        """
        return super(CigarViewSet, self).list(request, *args, **kwargs)

    @action()
    def set_price(self, request, pk):
        """An example action to on the ViewSet."""
        return Response('20$')

    @link()
    def get_price(self, request, pk):
        """Return the price of a cigar."""
        return Response('20$')

with supporting model and serializer:

class Cigar(models.Model):
    FORM_CHOICES = (
        ('parejo', 'Parejo'),
        ('torpedo', 'Torpedo'),
        ('pyramid', 'Pyramid'),
        ('perfecto', 'Perfecto'),
        ('presidente', 'Presidente'),
    )
    name = models.CharField(max_length=25, help_text='Cigar Name')
    colour = models.CharField(max_length=30, default="Brown")
    form = models.CharField(max_length=20, choices=FORM_CHOICES, default='parejo')
    gauge = models.IntegerField()
    length = models.IntegerField()
    price = models.DecimalField(decimal_places=2, max_digits=5)
    notes = models.TextField()
    manufacturer = models.ForeignKey('Manufacturer')

    def get_absolute_url(self):
        return "/api/cigars/%i/" % self.id

class CigarSerializer(serializers.ModelSerializer):
    url = fields.URLField(source='get_absolute_url', read_only=True)

    class Meta:
        model = models.Cigar

From this code, django-rest-swagger will produce the following swagger docs:

Function Based Views

django-rest-swagger also supports function based views. Since the serializers used by a function based view are not readily introspect-able, you can use the yaml parser to manually provide them.

This example also illustrates support for markdown.

def find_jambalaya(request):
    """
    Retrieve a *jambalaya* recipe by name or country of origin
    ---
    request_serializer: JambalayaQuerySerializer
    response_serializer: JambalayaSerializer
    """
    if request.method == 'POST':
        serializer = JambalayaQuerySerializer(data=request.DATA)
        if serializer.data['name'] is not None:
            j = Jambalaya.objects.filter(recipe__contains='name=%s' % serializer.data['name'])
        else:
            j = Jambalaya.objects.filter(recipe__contains="country=%s" % serializer.data['origin'])
        serializer = JambalayaSerializer(j, many=True)
        return Response(serializer.data)
    else:
        return Response("", status=status.HTTP_400_BAD_REQUEST)

YAML in the class docstring

You can put yaml in the class-level docstring of your view. It must be nested in the name of the method of interest:

class ArtisanCigarViewSet(viewsets.ModelViewSet):

    """
    Cigar resource.
    ---
    get_price:
        omit_serializer: true
    set_price:
        omit_serializer: true
        parameters_strategy:
            form: replace
        parameters:
            - name: price
              type: number
    """

    serializer_class = CigarSerializer
    model = Cigar
    queryset = Cigar.objects.all()

    def list(self, request, *args, **kwargs):
        """
        Return a list of objects.

        """
        return super(ArtisanCigarViewSet, self).list(request, *args, **kwargs)

    @action()
    def set_price(self, request, pk):
        """An example action to on the ViewSet."""
        return Response('20$')

    @link()
    def get_price(self, request, pk):
        """Return the price of a cigar."""
        return Response('20$')

Raw JSON objects

def create_cigar2(request):
    """
    ---
    response_serializer: CigarSerializer
    parameters:
        - name: body
          pytype: CigarSerializerMinimal
          paramType: body
    """
    in_serializer = CigarSerializerMinimal(data=request.DATA)
    if in_serializer.is_valid():
        cigar = Cigar()
        cigar.name = in_serializer.data['name']
        cigar.gauge = in_serializer.data['gauge']
        cigar.length = 2
        cigar.price = 2
        manufacturer = Manufacturer.objects.first()
        if manufacturer is None:
            manufacturer = Manufacturer()
            manufacturer.name = 'Taco tobacco'
            country = Country.objects.first()
            if country is None:
                country = Country()
                country.name = "Watchacallistan"
                country.save()
            manufacturer.country = country
            manufacturer.save()
        cigar.manufacturer = manufacturer
        cigar.save()
        out_serializer = CigarSerializer(cigar)
        return Response(out_serializer.data,
                        status=status.HTTP_201_CREATED)
    return Response(in_serializer.errors, status=status.HTTP_400_BAD_REQUEST)