Django REST framework 3.12
REST framework 3.12 brings a handful of refinements to the OpenAPI schema
generation, plus support for Django's new database-agnostic JSONField
,
and some improvements to the SearchFilter
class.
Grouping operations with tags.
Open API schemas will now automatically include tags, based on the first element in the URL path.
For example...
Method | Path | Tags |
---|---|---|
GET , PUT , PATCH , DELETE |
/users/{id}/ |
['users'] |
GET , POST |
/users/ |
['users'] |
GET , PUT , PATCH , DELETE |
/orders/{id}/ |
['orders'] |
GET , POST |
/orders/ |
['orders'] |
The tags used for a particular view may also be overridden...
class MyOrders(APIView):
schema = AutoSchema(tags=['users', 'orders'])
...
See the schema documentation for more information.
Customizing the operation ID.
REST framework automatically determines operation IDs to use in OpenAPI schemas. The latest version provides more control for overriding the behaviour used to generate the operation IDs.
See the schema documentation for more information.
Support for OpenAPI components.
In order to output more graceful OpenAPI schemes, REST framework 3.12 now defines components in the schema, and then references them inside request and response objects. This is in contrast with the previous approach, which fully expanded the request and response bodies for each operation.
The names used for a component default to using the serializer class name, but may be overridden if needed...
class MyOrders(APIView):
schema = AutoSchema(component_name="OrderDetails")
More Public API
Many methods on the AutoSchema
class have now been promoted to public API,
allowing you to more fully customize the schema generation. The following methods
are now available for overriding...
get_path_parameters
get_pagination_parameters
get_filter_parameters
get_request_body
get_responses
get_serializer
get_paginator
map_serializer
map_field
map_choice_field
map_field_validators
allows_filters
.
See the schema docs
for details on using custom AutoSchema
subclasses.
Support for JSONField.
Django 3.1 deprecated the existing django.contrib.postgres.fields.JSONField
in favour of a new database-agnositic JSONField
.
REST framework 3.12 now supports this new model field, and ModelSerializer
classes will correctly map the model field.
SearchFilter improvements
There are a couple of significant improvements to the SearchFilter
class.
Nested searches against JSONField and HStoreField
The class now supports nested search within JSONField
and HStoreField
, using
the double underscore notation for traversing which element of the field the
search should apply to.
class SitesSearchView(generics.ListAPIView):
"""
An API view to return a list of archaeological sites, optionally filtered
by a search against the site name or location. (Location searches are
matched against the region and country names.)
"""
queryset = Sites.objects.all()
serializer_class = SitesSerializer
filter_backends = [filters.SearchFilter]
search_fields = ['site_name', 'location__region', 'location__country']
Searches against annotate fields
Django allows querysets to create additional virtual fields, using the .annotate
method. We now support searching against annotate fields.
class PublisherSearchView(generics.ListAPIView):
"""
Search for publishers, optionally filtering the search against the average
rating of all their books.
"""
queryset = Publisher.objects.annotate(avg_rating=Avg('book__rating'))
serializer_class = PublisherSerializer
filter_backends = [filters.SearchFilter]
search_fields = ['avg_rating']
Funding
REST framework is a collaboratively funded project. If you use REST framework commercially we strongly encourage you to invest in its continued development by signing up for a paid plan.
Every single sign-up helps us make REST framework long-term financially sustainable.
Many thanks to all our wonderful sponsors, and in particular to our premium backers, Sentry, Stream, ESG, Rollbar, Cadre, Kloudless, Lights On Software, and Retool.