About dataclasses

allows you to specify class attributes and their types using type annotation syntax

attributes and their types are discoverable programmatically, allowing other modules to use them as more than just syntactic syntax, for example for validation.

In this blog post I will be showing how dataclasses can be used for django rest framework serializers using djangorestframework-dataclasses. This allows you to define classes to use in your application and also have them serialized for Django input and output.

About OpenAPI

OpenApi (or Swagger) allows you to document your API using JSON. It also provides a front-end where people consuming your API can see the API documentation and try calls on the fly.

Installing OpenAPI support for DRF

For the OpenAPI renderer, pyyaml and uritemplate are required for generating the API yaml documentation:

pip install pyyaml uritemplate

Once the dependencies are installed, you can automatically generate your swagger documentation by including two routes.

Firstly, to generate the yaml that will be used by openapi, call get_schema_view to get the DRF view for use in your urls.py:

Load the /docs/ route in your browser. If everything has been configured correctly, you should see the Swagger UI.

The Swagger UI allows you to see all of your API’s routes and parameters required, and even try API calls on the fly!

Installing the Dataclass serializer for DRF

As mentioned earlier, dataclass serializer allow you to convert python dataclasses to JSON and vice-versa, offering validation on user data.

Consider the following dataclass:

@dataclass
class Person():
name: str
age: int

Your users can submit JSON data with the name and age properties, and djangorestframework-dataclass will validate the data and deserialize into a Person object that you can directly use in your domain methods.

To install the module:

pip install djangorestframework-dataclasses

After installation, all you have to do to write your serializer is to inherit from DataclassSerializer and set the dataclass meta property.

person_serializer.validated_data will return an object of the Person class. This allows you to use your dataclasses as you want throughout your application.

What is more, the swagger documentation we implemented earlier allows you to see the input and output format for your person objects, provided by your serializers.

Click “try it out” to submit a person object with any values:

Once data is submitted, you can see the server response, allowing you to easily test and debug your API.

Conclusion

In conclusion, Swagger UI is a powerful documentation tool that can automatically generate documentation for any Django-Rest-Framework API. You can use it with any type of DRF serializer (such as ModelSerializer), but if you are wanting to use dataclasses and types for documentation, dataclass-serializer gives you an extra advantage: your code is documented not only for your frontend consumers but also for your backend developers