Django REST Framework 3.10 est sorti
par Makersquad ·
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 :
- Tester avec
python -3pour les warnings - Utiliser
2to3pour la conversion automatique - Vérifier les dépendances tierces
- 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.