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.
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.
The stack I prefer makes use of several additional modules you will require: django-rest-framework and drf-spectacular alongside Django. The rest framework helps you extend your application in order to have a REST API, while drf-spectacular will help you generate the OpenAPI spec.
After having the OpenAPI spec, you can generate clients with openapi-generator. There is an example I detailed for generating an Angular client.
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 https://github.com/nezhar/glt25-client.
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: https://github.com/nezhar/glt25-demo/compare/v1...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: https://github.com/nezhar/glt25-demo/compare/v2...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
The process can be automated even further using GitHub Actions and Dependabot.
Conclusion
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.