Django Ninja 1.8 est sorti
par Makersquad ·
Date de sortie : 8 novembre 2026
Documentation officielle : django-ninja 1.8.0
Django Ninja 1.8 apporte la documentation des webhooks dans OpenAPI 3.1, un register_field() plus précis, une lecture des corps multipart alignée sur Swagger et plusieurs changements de comportement autour de ModelSchema. Python 3.15 est désormais testé.
Les nouveautés principales
Webhooks dans OpenAPI 3.1
Décorez le schéma d’une charge utile avec @api.webhook ou @router.webhook : il apparaît dans la section webhooks d’OpenAPI 3.1, à côté des opérations, dans Swagger et Redoc. C’est de la documentation seulement : Ninja n’envoie rien.
from ninja import NinjaAPI, Router, Schema
api = NinjaAPI()
@api.webhook("order.paid")
class OrderPaid(Schema):
id: int
total: Decimal
router = Router(tags=["orders"])
@router.webhook # name defaults to the class name: "OrderShipped"
class OrderShipped(Schema):
id: int
register_field() accepte des classes de champ
Un champ Django personnalisé qui hérite d’un champ natif en reprend le type interne : l’enregistrer par son nom ("UUIDField") modifierait tous les UUIDField. On peut maintenant enregistrer la classe elle-même.
from typing import Annotated
from pydantic import BeforeValidator
from ninja.orm import register_field
class PublicIDField(models.UUIDField):
def from_db_value(self, value, expression, connection):
return PublicID(value)
register_field(PublicIDField, Annotated[str, BeforeValidator(str)])
L’enregistrement s’applique aussi aux sous-classes, la plus spécifique l’emporte, et il couvre les ForeignKey et OneToOneField qui pointent vers ce champ.
Paramètres de schéma optionnels
Un schéma Optional utilisé comme paramètre Query, Header ou Form retombe sur sa valeur par défaut quand aucun de ses champs n’est envoyé, au lieu de répondre 422.
class Filters(Schema):
city: str
year: int = 2026
@api.get("/events")
def events(request, filters: Filters | None = Query(None)):
...
# GET /events -> filters is None (was 422)
# GET /events?city=Kyiv -> Filters(city="Kyiv", year=2026)
Paramètres Body à côté de fichiers
Quand on mélange Body avec File ou Form, chaque partie multipart est lue comme l’envoient Swagger et les clients générés : les types primitifs (str, int, date, Enum, EmailStr…) en texte brut, les objets et les tableaux en JSON.
@api.post("/upload")
def upload(
request,
file: File[UploadedFile],
note: str = Body(...),
day: date = Body(...),
meta: dict[str, int] | None = Body(None),
):
...
# note='say "hi"' day=2024-01-02 meta='{"a": 1}' -> 200 (quoted strings and dates used to give 400)
Améliorations de ModelSchema
- Les champs du modèle viennent toujours en premier, dans l’ordre de
Meta.fields, puis les champs personnalisés dans leur ordre de déclaration. - Un champ déclaré sur le schéma est utilisé tel quel : un champ de modèle tiers que Ninja ne sait pas convertir ne casse plus
fields = "__all__". - Lister une clé étrangère par son attname (
user_id) dansMeta.fieldsdonne une erreur qui suggère la correction : utiliseruser, ou déclareruser_id: int. - Une clé étrangère ou un
OneToOneFielddirect prend son type de la cible duto_field, et non plus toujours de la clé primaire du modèle lié.
Documentation et fichiers pour assistants IA
La documentation de django-ninja.dev (s’ouvre dans un nouvel onglet) est réorganisée en quatre sections : Quick Start, Tutorial, Guide et About. Elle publie aussi des fichiers pour les LLM : /llms.txt (s’ouvre dans un nouvel onglet) (notes d’usage et lien vers chaque page) et /llms-full.txt (s’ouvre dans un nouvel onglet) (tout le Guide en un fichier). Chaque page est aussi servie en Markdown brut.
Python 3.15
Django Ninja est testé sur Python 3.15 avec Django 5.2, 6.0 et 6.1.
Corrections
CursorPaginationne répond plus 500 sur un curseur mal formé, ni sur une série de 100 lignes ou plus à égalité.- Un alias numérique (par exemple
alias="0") ne remet plus àNoneles champs d’une entrée objet. - Quand une instance d’une sous-classe est renvoyée, la réponse est filtrée par le schéma déclaré (déjà corrigé en 1.7.3) : les champs de la sous-classe ne fuient plus dans la réponse, comme avant 1.6.0.
exclude_unsetfonctionne pour les schémas imbriqués.- Les
examplesde paramètres donnés en liste ou en dictionnaire produisent un OpenAPI 3.1 valide : la forme liste ne fait plus planter Swagger UI (Body(examples={...})excepté). - Les surcharges d’authentification et de throttling fonctionnent pour les routeurs imbriqués (déjà corrigé en 1.7.2).
Changements incompatibles
- Le réglage
NINJA_PAGINATION_MAX_OFFSETest supprimé : une valeur laissée dans les réglages est ignorée. - Une
ForeignKeyou unOneToOneFieldavec unto_fieldest typé d’après le champ cible. Avec unto_fieldde type chaîne qui contient des valeurs numériques, les réponses renvoient"123"au lieu de123. ModelSchemaplace les champs du modèle (dans l’ordre deMeta.fields) avant les champs personnalisés, ce qui change l’ordre des clés dans les réponses et dans OpenAPI.- Déclarer un champ sur un
ModelSchemaet le lister aussi dansMeta.fieldsémet unDeprecationWarning, qui deviendra uneConfigErrordans une release ultérieure. - Les champs
ForeignKeyetOneToOneFieldnullables avecdepth > 0sontOptionaldans le schéma (anyOf: [..., null]). - Les réponses paginées d’éléments
UnionouAnnotatedont leurs propres noms de schéma (PagedFooOrBarau lieu d’unPagedUnionouPagedAnnotatedpartagé) : les modèles des clients générés peuvent être renommés. - Dans une requête multipart, une partie
Bodyde typestrenvoyée avec des guillemets littéraux autour les conserve.
À retenir
Django Ninja 1.8 se met à jour avec un œil sur les schémas : l’ordre des champs de ModelSchema, le typage des clés étrangères et les noms de schémas paginés changent, ce qui se voit dans les réponses, dans OpenAPI et dans les clients générés. En échange, les webhooks se documentent, register_field() cible une classe et les corps multipart se lisent comme les envoient les outils.