Django REST Framework 3.12 est sorti

Date de sortie : 28 septembre 2020

Documentation officielle : DRF 3.12 Announcement

DRF 3.12 peaufine l’expérience OpenAPI. Tags automatiques, operation IDs personnalisables, et support du tout nouveau JSONField de Django 3.1. Une release d’amélioration continue qui fait du bien.

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"

# Personnalisation
class UserViewSet(viewsets.ModelViewSet):
    @extend_schema(tags=['account'])
    def me(self, request):
        ...

Customisation des Operation IDs

def custom_operation_id(self, path, method):
    return f"{method.lower()}_{path.replace('/', '_')}"

schema_view = get_schema_view(
    title="My API",
    generator_class=CustomSchemaGenerator
)

Support de JSONField

Support natif du JSONField agnostique de Django 3.1 :

from django.db import models

class Product(models.Model):
    metadata = models.JSONField(default=dict)

class ProductSerializer(serializers.ModelSerializer):
    class Meta:
        model = Product
        fields = ['id', 'name', 'metadata']

Améliorations de SearchFilter

Recherche dans les champs imbriqués :

class ProductViewSet(viewsets.ModelViewSet):
    search_fields = [
        'name',
        'category__name',
        '=sku',  # Exact match
        '^name',  # Starts with
        '@description',  # Full-text (PostgreSQL)
    ]

Components OpenAPI publics

L’API pour définir des components réutilisables est maintenant publique :

from rest_framework.schemas.openapi import SchemaGenerator

class CustomSchemaGenerator(SchemaGenerator):
    def get_schema(self, *args, **kwargs):
        schema = super().get_schema(*args, **kwargs)
        schema['components']['schemas']['Error'] = {
            'type': 'object',
            'properties': {
                'detail': {'type': 'string'}
            }
        }
        return schema

Dépréciation de NullBooleanField

NullBooleanField est déprécié. Utilisez BooleanField(allow_null=True) à la place.

À retenir

Si vous générez une doc OpenAPI, les tags automatiques vont nettoyer votre schéma sans effort. Et si vous êtes sur Django 3.1, le support JSONField fonctionne out of the box.