EN BREF
OpenAPI 3.1 a ajouté la compatibilité complète avec JSON Schema, les webhooks et des améliorations au discriminateur. OpenAPI 3.2 a ajouté la prise en charge de la méthode QUERY, des exemples améliorés et de meilleures définitions de sécurité. Modern PetstoreAPI utilise OpenAPI 3.2 pour démontrer toutes les dernières fonctionnalités avec des exemples prêts pour la production.
Introduction
Vous êtes en train de rédiger une spécification OpenAPI. Vous voyez des références à OpenAPI 3.0, 3.1 et 3.2. Quelle est la différence ? Devez-vous effectuer une mise à niveau ? Vos outils prendront-ils en charge la nouvelle version ?
OpenAPI a considérablement évolué de 3.0 à 3.2. Chaque version ajoute des fonctionnalités qui rendent les spécifications d'API plus puissantes et précises. Mais tous les outils ne prennent pas en charge les dernières versions, ce qui crée un défi de compatibilité.
L'ancien Swagger Petstore utilise OpenAPI 2.0 (spécification Swagger). Modern PetstoreAPI utilise OpenAPI 3.2, présentant chaque nouvelle fonctionnalité avec des exemples prêts pour la production.
Dans ce guide, vous apprendrez ce qui a changé dans chaque version d'OpenAPI, comment choisir la bonne version et comment Modern PetstoreAPI démontre les fonctionnalités d'OpenAPI 3.2.
OpenAPI 3.0 : La base
OpenAPI 3.0 (publié en juillet 2017) était une mise à jour majeure de Swagger 2.0.
Fonctionnalités clés
1. Plusieurs serveurs
servers:
- url: https://api.petstoreapi.com/v1
description: Production
- url: https://staging.petstoreapi.com/v1
description: Staging
Swagger 2.0 ne supportait qu'un seul hôte.
2. Objet de corps de requête
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Pet'
Plus clair que le paramètre body de Swagger 2.0.
3. Composants pour la réutilisabilité
components:
schemas:
Pet:
type: object
responses:
NotFound:
description: Ressource introuvable
parameters:
PetId:
name: petId
in: path
Meilleure organisation que les definitions de Swagger 2.0.
4. Callbacks
Définir des callbacks asynchrones (webhooks) :
callbacks:
orderUpdate:
'{$request.body#/callbackUrl}':
post:
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/OrderUpdate'
5. Liens
Définir les relations entre les opérations :
links:
GetPetByPetId:
operationId: getPetById
parameters:
petId: '$response.body#/id'
Limitations
1. Incompatibilité JSON Schema
OpenAPI 3.0 utilisait un sous-ensemble de JSON Schema Draft 5, et non la totalité de JSON Schema. Cela entraînait des problèmes de validation.
2. Pas d'objet webhooks
Les webhooks étaient définis comme des callbacks, ce qui était source de confusion.
3. Discriminateur limité
La prise en charge du polymorphisme était basique.
4. Pas de type null
Vous ne pouviez pas spécifier type: null directement.
OpenAPI 3.1 : Changements majeurs
OpenAPI 3.1 (publié en février 2021) s'est concentré sur l'alignement avec JSON Schema.
1. Compatibilité complète avec JSON Schema 2020-12
Le plus grand changement : Les schémas OpenAPI 3.1 sont valides pour JSON Schema 2020-12.
Avant (OpenAPI 3.0) :
type: string
nullable: true # Spécifique à OpenAPI
Après (OpenAPI 3.1) :
type: [string, "null"] # JSON Schema standard
Avantages :
- Utiliser n'importe quel validateur JSON Schema
- Partager des schémas entre OpenAPI et d'autres outils
- Accès à toutes les fonctionnalités de JSON Schema
2. Objet Webhooks
Avant (OpenAPI 3.0) :
# Webhooks définis comme des callbacks (source de confusion)
paths:
/subscribe:
post:
callbacks:
orderUpdate:
# définition du webhook
Après (OpenAPI 3.1) :
webhooks:
orderUpdate:
post:
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/OrderUpdate'
Séparation plus claire entre les points d'API et les webhooks.
3. Discriminateur amélioré
Meilleure prise en charge du polymorphisme :
oneOf:
- $ref: '#/components/schemas/Cat'
- $ref: '#/components/schemas/Dog'
discriminator:
propertyName: petType
mapping:
cat: '#/components/schemas/Cat'
dog: '#/components/schemas/Dog'
4. Identifiant de licence de l'objet Info
info:
license:
name: MIT
identifier: MIT # Identifiant SPDX
5. PathItem $ref
Référencez des éléments de chemin complets :
paths:
/pets:
$ref: '#/components/pathItems/PetsCollection'
Changements cassants
1. nullable supprimé
Utilisez type: [string, "null"] à la place.
2. exclusiveMinimum/exclusiveMaximum modifié
Maintenant booléen, non numérique.
3. example vs examples
Validation plus stricte.
OpenAPI 3.2 : Dernières fonctionnalités
OpenAPI 3.2 (date de sortie à déterminer, brouillon disponible) ajoute des modèles d'API modernes.
1. Prise en charge de la méthode QUERY
Méthode HTTP QUERY pour les recherches complexes :
paths:
/pets/search:
query: # Nouvelle méthode
requestBody:
content:
application/json:
schema:
type: object
properties:
filters:
type: object
sort:
type: array
responses:
'200':
description: Résultats de la recherche
Modern PetstoreAPI utilise QUERY pour les recherches complexes d'animaux de compagnie.
2. Exemples améliorés
Plusieurs exemples avec métadonnées :
examples:
availableCat:
summary: Chat disponible
description: Un chat disponible à l'adoption
value:
id: "019b4132-70aa-764f-b315-e2803d882a24"
name: "Fluffy"
species: "CAT"
status: "DISPONIBLE"
adoptedDog:
summary: Chien adopté
value:
id: "019b4127-54d5-76d9-b626-0d4c7bfce5b6"
name: "Buddy"
species: "DOG"
status: "ADOPTÉ"
3. Définitions de sécurité améliorées
Meilleure prise en charge d'OAuth 2.0 :
components:
securitySchemes:
oauth2:
type: oauth2
flows:
authorizationCode:
authorizationUrl: https://petstoreapi.com/oauth/authorize
tokenUrl: https://petstoreapi.com/oauth/token
refreshUrl: https://petstoreapi.com/oauth/refresh
scopes:
pets:read: Lire les animaux
pets:write: Créer et mettre à jour des animaux
orders:read: Lire les commandes
4. Mappage de discriminateur amélioré
Polymorphisme plus flexible :
discriminator:
propertyName: type
mapping:
cat: Cat
dog: Dog
bird: '#/components/schemas/Bird' # Peut mélanger les références locales et $ref
5. Meilleure prise en charge de l'obsolescence
Déprécier des champs spécifiques :
properties:
oldField:
type: string
deprecated: true
description: Utiliser newField à la place
newField:
type: string
Comment Modern PetstoreAPI utilise OpenAPI 3.2
Modern PetstoreAPI présente chaque fonctionnalité d'OpenAPI 3.2.
1. Spécification complète
La spécification OpenAPI 3.2 complète est disponible à l'adresse :
https://petstoreapi.com/openapi.json
2. Méthode QUERY pour les recherches complexes
/pets/search:
query:
summary: Rechercher des animaux avec des critères complexes
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/PetSearchQuery'
3. Webhooks
webhooks:
petStatusChanged:
post:
summary: Statut de l'animal modifié
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/PetStatusWebhook'
4. Schémas polymorphes
Pet:
oneOf:
- $ref: '#/components/schemas/Cat'
- $ref: '#/components/schemas/Dog'
- $ref: '#/components/schemas/Bird'
discriminator:
propertyName: species
5. Exemples exhaustifs
Chaque point d'accès inclut plusieurs exemples montrant différents scénarios.
6. Réponses d'erreur RFC 9457
responses:
'400':
description: Requête incorrecte
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDetails'
Consultez la spécification OpenAPI complète pour toutes les fonctionnalités.
Guide de migration
De 3.0 à 3.1
1. Remplacer nullable :
# Avant
type: string
nullable: true
# Après
type: [string, "null"]
2. Mettre à jour exclusiveMinimum/exclusiveMaximum :
# Avant
minimum: 0
exclusiveMinimum: true
# Après
minimum: 0
exclusiveMinimum: 0
3. Déplacer les webhooks :
# Avant
paths:
/subscribe:
callbacks:
# webhook
# Après
webhooks:
# webhook
De 3.1 à 3.2
1. Ajouter des méthodes QUERY si nécessaire :
/pets/search:
query: # Nouveau en 3.2
# recherche complexe
2. Améliorer les exemples :
examples:
example1:
summary: Description
value: {...}
3. Mettre à jour les définitions de sécurité :
Ajouter refreshUrl aux flux OAuth.
Tester les spécifications OpenAPI avec Apidog
Apidog prend en charge toutes les versions d'OpenAPI.
Importer une spécification OpenAPI
1. Ouvrir Apidog
2. Cliquer sur "Importer"
3. Sélectionner "OpenAPI 3.x"
4. Coller l'URL ou télécharger le fichier
5. Apidog valide et importe
Valider la spécification
Apidog vérifie :
- Validité du schéma
- Intégrité des références
- Exactitude des exemples
- Complétude de la définition de sécurité
Tester l'implémentation de l'API
Générer des cas de test à partir de la spécification :
- Validation des requêtes
- Validation des réponses
- Vérifications des codes de statut
- Conformité au schéma
Comparaison des versions
Importer plusieurs versions et comparer :
- Changements cassants
- Nouveaux points d'accès
- Changements de schéma
- Champs dépréciés
Conclusion
OpenAPI a considérablement évolué :
OpenAPI 3.0 : Fondation avec serveurs, corps de requête, callbacks
OpenAPI 3.1 : Compatibilité JSON Schema, objet webhooks, meilleur polymorphisme
OpenAPI 3.2 : Méthode QUERY, exemples améliorés, sécurité renforcée
Modern PetstoreAPI utilise OpenAPI 3.2 pour démontrer toutes les fonctionnalités avec des exemples prêts pour la production. C'est l'implémentation de référence pour la conception d'API modernes.
Utilisez Apidog pour travailler avec n'importe quelle version d'OpenAPI, valider les spécifications et tester les implémentations.
FAQ
Dois-je passer à OpenAPI 3.1 ou 3.2 ?
Si vos outils le prennent en charge, oui. La compatibilité de JSON Schema d'OpenAPI 3.1 est précieuse. OpenAPI 3.2 ajoute des modèles modernes comme la méthode QUERY.
Ma spécification OpenAPI 3.0 fonctionnera-t-elle avec les outils 3.1 ?
En grande partie, mais nullable et exclusiveMinimum/exclusiveMaximum nécessitent des mises à jour.
Les générateurs de code prennent-ils en charge OpenAPI 3.2 ?
Le support s'accroît. Vérifiez la documentation de votre générateur. Beaucoup prennent en charge la version 3.1, moins la version 3.2.
Puis-je utiliser les fonctionnalités d'OpenAPI 3.2 dans la version 3.1 ?
Non. Utilisez la version qui correspond à vos fonctionnalités. Si vous avez besoin de la méthode QUERY, utilisez la version 3.2.
Comment valider ma spécification OpenAPI ?
Utilisez Apidog pour importer et valider votre spécification. Il vérifie la validité du schéma et l'intégrité des références.
Où puis-je voir un exemple complet d'OpenAPI 3.2 ?
Modern PetstoreAPI fournit une spécification OpenAPI 3.2 complète et prête pour la production.
Quelle est la différence entre les webhooks et les callbacks ?
Les webhooks sont des requêtes HTTP du serveur au client. Les callbacks sont définis dans OpenAPI 3.0 dans le cadre des opérations. OpenAPI 3.1+ dispose d'un objet webhooks dédié.
Dois-je utiliser JSON ou YAML pour les spécifications OpenAPI ?
Les deux fonctionnent. YAML est plus lisible pour les humains. JSON est plus facile pour les outils. Modern PetstoreAPI fournit les deux formats.