Aller au contenu
Makersquad

Django REST Framework 3.10 est sorti

par Makersquad ·

Logo de Django REST framework sur fond dégradé

Date de sortie : 15 juillet 2019

Documentation officielle : DRF 3.10 Announcement

DRF 3.10 abandonne le support de Python 2 et remplace la génération de schémas CoreAPI par une génération OpenAPI, dont elle amorce la dépréciation.

Les nouveautés principales

Fin du support Python 2 (enfin !)

DRF 3.10 abandonne le support de Python 2. Il faut donc être passé à Python 3 avant d’upgrader.

Versions supportées :

  • Python 3.5, 3.6, 3.7
  • Django 1.11, 2.0, 2.1, 2.2

Génération de schémas OpenAPI

Depuis l’introduction des schémas dans DRF 3.5, OpenAPI s’est imposé comme le standard largement adopté pour décrire les APIs web. Cette version amorce la dépréciation de la génération de schémas basée sur CoreAPI et introduit à sa place la génération OpenAPI.

Vous pouvez générer un schéma statique avec la commande de gestion generateschema, ou faire servir le schéma par le projet avec le raccourci get_schema_view(), dans votre urls.py :

from rest_framework.schemas import get_schema_view

urlpatterns = [
    # ...
    # Use the `get_schema_view()` helper to add a `SchemaView` to project URLs.
    #   * `title` and `description` parameters are passed to `SchemaGenerator`.
    #   * Provide view name for use with `reverse()`.
    path(
        "openapi",
        get_schema_view(title="Your Project", description="API for all things …"),
        name="openapi-schema",
    ),
    # ...
]

Le paramètre version de get_schema_view() n’existe pas encore dans 3.10.0 : la version de l’API est incluse dans le schéma à partir de la 3.10.3.

Pour une personnalisation qui s’applique à toute l’API, héritez de rest_framework.schemas.openapi.SchemaGenerator et passez cette classe à la commande generateschema ou à get_schema_view(). Pour une personnalisation propre à une vue, héritez de AutoSchema et définissez schema = <VotreClasse> sur la vue.

La version 3.10.1 exige désormais uritemplate pour la génération de schémas OpenAPI, mais plus coreapi.

Dépréciation de CoreAPI

Cette version amorce le processus de dépréciation de la génération de schémas basée sur CoreAPI. Si vous utilisez les schémas CoreAPI, vous devez déclarer explicitement DEFAULT_SCHEMA_CLASS dans vos réglages DRF :

REST_FRAMEWORK = {
    ...: ...,
    "DEFAULT_SCHEMA_CLASS": "rest_framework.schemas.coreapi.AutoSchema",
}

Vous pouvez continuer à utiliser les schémas, la documentation d’API et le client CoreAPI dans un avenir prévisible. Le générateur CoreAPI doit être retiré de DRF dans la version 3.12, mais les mainteneurs visent à le garder disponible comme paquet tiers.

Pourquoi OpenAPI ?

  • Standard largement adopté pour décrire les APIs web
  • Des outils tiers de documentation d’API s’appuient sur le schéma OpenAPI
  • Les mainteneurs prévoient des améliorations itératives des schémas générés dans les versions correctives

Migration Python 2 vers 3

Si vous êtes encore sur Python 2 :

  1. Tester avec python -3 pour les warnings
  2. Utiliser 2to3 pour la conversion automatique
  3. Vérifier les dépendances tierces
  4. Migrer vers Python 3.6+ pour profiter des features modernes

À retenir

DRF 3.10 abandonne Python 2 et passe à la génération de schémas OpenAPI. Si vous utilisez des schémas CoreAPI, déclarez DEFAULT_SCHEMA_CLASS explicitement dès maintenant, car le générateur CoreAPI doit être retiré dans la version 3.12.

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