Django REST Framework 3.12 est sorti
par Makersquad ·
Date de sortie : 28 septembre 2020
Documentation officielle : DRF 3.12 Announcement
DRF 3.12 apporte une série d’améliorations à la génération de schémas OpenAPI (tags automatiques, operation IDs personnalisables, components), la prise en charge du nouveau JSONField de Django 3.1 et des améliorations de SearchFilter.
Les nouveautés principales
Tags OpenAPI automatiques
Les opérations sont automatiquement groupées par tags basés sur le premier élément de l’URL :
# /users/ → tag "users"
# /orders/ → tag "orders"
Les tags d’une vue peuvent être redéfinis avec AutoSchema :
class MyOrders(APIView):
schema = AutoSchema(tags=["users", "orders"])
...
Customisation des Operation IDs
DRF détermine automatiquement les operation IDs utilisés dans les schémas OpenAPI. Cette version donne plus de contrôle pour surcharger le comportement qui les génère, à travers la classe AutoSchema (voir la documentation des schémas).
Support de JSONField
Django 3.1 a déprécié l’ancien django.contrib.postgres.fields.JSONField au profit d’un nouveau JSONField indépendant de la base de données. DRF 3.12 prend en charge ce nouveau champ de modèle, et les classes ModelSerializer le mappent correctement.
Améliorations de SearchFilter
SearchFilter reçoit deux améliorations notables. La première est la recherche imbriquée dans les champs JSONField et HStoreField, avec la notation à double tiret bas pour désigner l’élément du champ visé :
class SitesSearchView(generics.ListAPIView):
queryset = Sites.objects.all()
serializer_class = SitesSerializer
filter_backends = [filters.SearchFilter]
search_fields = ["site_name", "location__region", "location__country"]
La seconde est la recherche sur les champs ajoutés par annotate() :
class PublisherSearchView(generics.ListAPIView):
queryset = Publisher.objects.annotate(avg_rating=Avg("book__rating"))
serializer_class = PublisherSerializer
filter_backends = [filters.SearchFilter]
search_fields = ["avg_rating"]
Components OpenAPI
Pour produire des schémas OpenAPI plus propres, DRF 3.12 définit désormais des components dans le schéma, puis les référence dans les objets de requête et de réponse. L’ancienne approche développait entièrement les corps de requête et de réponse pour chaque opération.
Le nom d’un component est par défaut celui de la classe de serializer, mais il peut être redéfini :
class MyOrders(APIView):
schema = AutoSchema(component_name="OrderDetails")
Plusieurs méthodes de la classe AutoSchema passent aussi dans l’API publique et peuvent être surchargées pour personnaliser la génération : 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 et allows_filters.
Dépréciation de NullBooleanField
NullBooleanField passe en dépréciation en attente, avec une suppression prévue pour la 3.14. Utilisez BooleanField(allow_null=True) à la place.
À retenir
Si vous générez une doc OpenAPI, les tags sont désormais inclus automatiquement et les schémas utilisent des components. Si vous êtes sur Django 3.1, ModelSerializer mappe le nouveau JSONField.