Aller au contenu
Makersquad

Django Ninja 1.8 est sorti

par Makersquad ·

Logo de Django Ninja sur fond dégradé

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) dans Meta.fields donne une erreur qui suggère la correction : utiliser user, ou déclarer user_id: int.
  • Une clé étrangère ou un OneToOneField direct prend son type de la cible du to_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

  • CursorPagination ne 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 à None les 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_unset fonctionne pour les schémas imbriqués.
  • Les examples de 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_OFFSET est supprimé : une valeur laissée dans les réglages est ignorée.
  • Une ForeignKey ou un OneToOneField avec un to_field est typé d’après le champ cible. Avec un to_field de type chaîne qui contient des valeurs numériques, les réponses renvoient "123" au lieu de 123.
  • ModelSchema place les champs du modèle (dans l’ordre de Meta.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 ModelSchema et le lister aussi dans Meta.fields émet un DeprecationWarning, qui deviendra une ConfigError dans une release ultérieure.
  • Les champs ForeignKey et OneToOneField nullables avec depth > 0 sont Optional dans le schéma (anyOf: [..., null]).
  • Les réponses paginées d’éléments Union ou Annotated ont leurs propres noms de schéma (PagedFooOrBar au lieu d’un PagedUnion ou PagedAnnotated partagé) : les modèles des clients générés peuvent être renommés.
  • Dans une requête multipart, une partie Body de type str envoyé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.

É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.