Aller au contenu
Makersquad

Django REST Framework 3.12 est sorti

par Makersquad ·

Logo de Django REST framework sur fond dégradé

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.

Échanger avec un expert Django

De l’idée au marché. Makersquad conçoit des logiciels sur mesure, pensés pour durer, avec de petites équipes d’experts autonomes. Depuis 2018.