Building better APIs: from Django to client libraries with OpenAPI
tl;dr
A summary of resources and learnings related to building REST API I put together over the last couple of years. Complete API development workflow from Django backend to frontend clients using Django REST Framework, drf-spectacular for OpenAPI spec generation, and automated client generation with openapi-generator. Big productivity boost!
There is a lot of discussion about frameworks for building REST APIs, some of them being even able to generate OpenAPI specs directly for you. Django is not quite known for that, but there are ways of doing this by automating most of the process while being very productive and offering your team a clean developer experience.
Overview
The stack I prefer makes use of several additional modules you will require: django-rest-framework and drf-spectacular alongside Django. REST Framework helps you extend your application in order to have a REST API, while drf-spectacular will help you the ability to generate the OpenAPI spec (standalone post: Create OpenAPI spec for Django REST Framework APIs.
After having the OpenAPI spec, you can generate clients with openapi-generator. Here is an example I mapped out of generating an Angular client:
Step-by-step process
There is also a recording from my GLT 2025 talk where I summarize most of these ideas.
In case you want to follow along, here is a step-by-step guide from the repository I showed during the presentation:
- Create a Django project
- Add a Django app
- Models and database migrations
- DRF serializers
- DRF views
- Configure URLs
- Add and configure drf spectacular
- Generate OpenAPI
From the last step, you can generate the API clients for the platform you require. You can follow the README and the examples available in my glt25-client repository.
Maintaining compatibility over time
The final tool you can use is openapi-diff, which will help you keep your documentation compatible. This is very important once your REST API is used in production:
Example of a compatible change: glt25-demo v1 to v2
docker run --rm -t openapitools/openapi-diff:latest https://github.com/nezhar/glt25-demo/releases/download/v1/openapi.yaml https://github.com/nezhar/glt25-demo/releases/download/v2/openapi.yaml
Example of a breaking change: glt25-demo v2 to v3
docker run --rm -t openapitools/openapi-diff:latest https://github.com/nezhar/glt25-demo/releases/download/v2/openapi.yaml https://github.com/nezhar/glt25-demo/releases/download/v3/openapi.yaml
Automating the maintenance
The process can be automated even further using GitHub Actions and Dependabot. Here are what the steps look like with this full continuous delivery setup:
Takeways
Building a complete API development workflow from Django to client libraries using OpenAPI creates a powerful and maintainable development experience. By combining Django REST Framework with drf-spectacular for automatic OpenAPI spec generation and openapi-generator for client creation, you can eliminate manual API documentation and reduce integration errors.
If you want to go even further, you can automate the integration of error codes inside the OpenAPI spec. This way you can better support languages that are even more strict when consuming the REST API!
Thank you to Harald Nezbeda for proposing this guest post on the Django blog!
