Django Rest Swagger for SDK generation — no extra code required

If you ever need to generate an SDK for an API you’ve built, you can make your life a lot easier by doing it in with Django Rest Framework and adding some Swagger magic.

The overview is a really cool workflow that could be very easily automated.

1. Write an endpoint with the Django Rest Framework in your project
2. Add Django-Rest-Swagger on top of this to generate an openAPI spec, it does this when it gives you request the “swagger” interface
3. Tell use the generated openAPI spec to generate an api using Swagger-codegen

1. Install everything (I’m assuming you have a Django project here)

pip install django-rest-framework
pip install django-rest-swagger
brew install swagger-codegen

2 . Add these to your project

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

3. Write an API

from django.contrib.auth import get_user_model
from rest_framework import generics
from rest_framework import serializers
class UserSerializer(serializers.ModelSerializer):
    class Meta:
        model = get_user_model() # Any model
        exclude = ('password', )
class UserList(generics.ListAPIView):
    queryset = get_user_model().objects.all() # Any queryset
    serializer_class = UserSerializer

4. Configure your urls

# API urls config
from django.conf.urls import url
from django.contrib import admin
from .views import UserList
urlpatterns = [
    
    url(r'^api/user/$', UserList.as_view(), name='user-list'),
]
# Project urls (the one that's exposed publicly in the settings) 
from django.conf.urls import url, include
from django.contrib import admin
from rest_framework_swagger.views import get_swagger_view
schema_view = get_swagger_view(title='User API')
urlpatterns = [
    url(r'^admin/', admin.site.urls),
    url(r'^', include('api.urls', namespace='api')),
    url(r'^$', schema_view),
]

5. View the swagger Interface which allows you to test requests in the browser

6. Get the OpenAPI document

• When your server was attempting to render the page above, it generated a file. In your logs it will look like

• The request for /?=format=openapi is a file that’s automatically generated by inspecting the url structure, serialisers and the actions can be performed on each view (get, post, put, patch, delete)

7. Generate your SDK

• The file we generated above is a valid openapi spec. We can use it to generate code in different languages with the Swagger-codegen tool (check the official documentation for officially supported languages)
• With the server running (the easiest way I found to do it)…

swagger-codegen generate -i http://localhost:8000/?format=openapi -l typescript-fetch -o sdk-typescript-fetch/
swagger-codegen generate -i http://localhost:8000/?format=openapi -l python -o sdk-python/
swagger-codegen generate -i http://localhost:8000/?format=openapi -l swift -o sdk-swift/

8. Use the SDK

• Above I generated a typescript fetch api to a file called api.ts. This implements a class called UserApi with the function ‘read’ which matches the operation id that was generated earlier
• I generated another in python which also implements a class called UserAPI and a function called read. Utilising the urllib as the client. It also generates tests based on the spec that’s provided.
• The last was swift which uses alamofire as the client and also generates to the standard spec of a class called UserApi and a function called ‘read’

Notes

• Response types and codes aren’t covered in the generated openAPI spec. If you have a custom response that you need generated, it might be necessary to download and edit the file
• Operation ids aren’t super descriptive or clear about how they’re generated by Django rest swagger. It can be nice to update them to something that makes sense for the consumers of your API or workout an automated way of defining them