Swagger APi with Django Rest Framework

Swagger is a popular tool for creating and documenting APIs. It allows developers to easily visualize and interact with the API endpoints, as well as automate the generation of client libraries and server code. Django REST framework is a powerful toolkit for building APIs in the Django web framework. In this article, we’ll show you how to use Swagger with Django REST framework to create and document a robust, production-ready API.

To get started, you’ll need to install both Django REST framework and the Django Swagger package. You can do this using pip:

pip install djangorestframework
pip install django-rest-swagger

Next, add rest_framework and swagger to your INSTALLED_APPS in your Django settings file:

INSTALLED_APPS = [
    ...
    'rest_framework',
    'swagger',
]

Next, you’ll need to define the API endpoints in your Django views. Django REST framework makes it easy to define and customize API views using classes and mixins. For example, here’s a simple view that lists all the users in the system:

from rest_framework import generics
from .models import User
from .serializers import UserSerializer

class UserListView(generics.ListCreateAPIView):
    queryset = User.objects.all()
    serializer_class = UserSerializer

To include this view in the Swagger documentation, you’ll need to add a swagger_schema decorator to the view class. The decorator takes a dictionary of parameters that define the details of the API endpoint, such as the HTTP method, the request and response schemas, and any parameters or query string arguments. Here's an example of how you might use the decorator to document the UserListView:

from swagger.decorators import swagger_schema

@swagger_schema(
    request={
        'parameters': [
            {
                'name': 'limit',
                'required': False,
                'type': 'integer',
                'in': 'query',
                'description': 'The maximum number of users to return in the response.'
            },
            {
                'name': 'offset',
                'required': False,
                'type': 'integer',
                'in': 'query',
                'description': 'The number of users to skip in the response.'
            }
        ]
    },
    responses={
        '200': {
            'description': 'A list of users',
            'schema': UserSerializer
        }
    }
)
class UserListView(generics.ListCreateAPIView):
    queryset = User.objects.all()
    serializer_class = UserSerializer

With the API endpoints defined, you can now generate the Swagger documentation by visiting the /swagger/ URL in your Django project. The Django Swagger package provides a built-in view and template for displaying the documentation, which you can customize to match your API's branding and style.

Swagger provides your API with thorough documentation, but it also has a number of other advantages. For instance, you can quickly test your API endpoints using the Swagger UI and view the request and response data in real-time.

All of the API endpoints in your Django project are listed in the Swagger UI along with their arguments, request and response data, and other information. You can use the UI to test each endpoint by entering the appropriate values in the form fields and clicking the “Try it out!” button. For example, if you have an endpoint that allows you to create a new user, you can enter the user’s data in the form fields and click “Try it out!” to see the request and response data.

Here’s an example of how you might use the Swagger UI to test an endpoint that lists all the users in the system:

1. Navigate to the /swagger/ URL in your Django project.
2. Click on the “User List” endpoint in the list of endpoints.
3. Enter any desired parameters, such as the limit and offset, in the form fields.
4. Click the “Try it out!” button.
5. The Swagger UI will display the request and response data for the endpoint.

Testing and debugging your API endpoints can be done quickly and easily by using the Swagger UI. When creating and troubleshooting your API, being able to observe the request and response data in real-time can be quite beneficial.

The Swagger UI not only lets you test endpoints but also makes it simple to view the documentation for each API. As it offers a clear and succinct description of the API’s features and usage, this can be helpful when working with a team or when onboarding new developers.

Overall, any developer working with the Django REST framework and APIs will find the Swagger UI to be a useful tool. It makes it simple to test and debug your endpoints and to provide thorough API documentation.