Support de OpenAPI Specification 3.0
OpenAPI Specification 3.0 propose de nouvelles fonctionnalités permettant d'apporter plus d'expressivité et de productivité aux concepteurs d'API.
Pour plus d'informations concernant OpenAPI, consultez la documentation de Swagger (en anglais).
Composants
- variables de chemins ;
- paramètres de requêtes ;
- en-têtes ;
- réponses.
Combinaisons
- Composition (allOf) vous permet d'agréger des propriétés de schéma de différents schémas. Par exemple, vous pouvez définir un type de données anatomy en réutilisant des propriétés de types existants nervousSystem, skeleton et digestiveSystem.
- Le polymorphisme (oneOf/anyOf) vous permet de créer une entité pouvant utiliser les propriétés de différents types de données.
- oneOf vous permet de définir un type de données contenant des propriétés de l'un des types sélectionnés. Par exemple, si vous créez une opération pour obtenir des informations sur un organe, vous pouvez définir la réponse à l'aide de la combinaison oneOf pour obtenir toutes les propriétés de brain ou bien toutes les propriétés de heart.
- anyOf vous permet de définir un type de données contenant les propriétés d'un ou plusieurs des types sélectionnés. Par exemple, vous pouvez définir un type de données nervousSystem et un type skeleton contenant différentes propriétés, puis utiliser la combinaison anyOf pour créer un type de données contenant des propriétés de l'un de ces types.
Une combinaison anyOf est valide tant qu'elle contient tous les paramètres requis d'au moins un des types sélectionnés. Les exemples ci-dessous utilisent la propriété brain_weigth du type nervousSystem et les propriétés skull_height et teeth de skeleton.
- oneOf vous permet de définir un type de données contenant des propriétés de l'un des types sélectionnés. Par exemple, si vous créez une opération pour obtenir des informations sur un organe, vous pouvez définir la réponse à l'aide de la combinaison oneOf pour obtenir toutes les propriétés de brain ou bien toutes les propriétés de heart.
Pour plus d'informations concernant la composition et le polymorphisme, consultez les articles Inheritance and Polymorphism et Difference Between anyOf and oneOf (en anglais).
Réponses
- Response ranges : au lieu de définir un code de statut tel que 200, vous pouvez le définir tel que 2XX, de façon à ce qu'il inclut les codes entre 200 et 299.
- Default responses : vous pouvez définir une réponse par défaut à retourner lorsque aucune famille de code de statut ou aucun code de statut spécifique n'est défini.
- la réponse 204 est définie et est prioritaire sur les autres ;
- la réponse 2XX s'applique aux codes de réponse 200 à 203 et 205 à 299 ;
- La réponse default s'applique à toutes les réponses 1XX, 3XX, 4XX et 5XX.
Sécurité
- authentification Bearer ;
- OpenIdConnect.
Restrictions
OAS 3.0 vous permet d'indiquer que certaines propriétés sont en lecture seule ou en écriture seule.
Cette option n'est disponible que dans les types de données et ne peut être définie dans des requêtes ou des réponses au niveau des opérations.
