Support de OpenAPI Specification 3.0

Concevez une API avec OpenAPI Specification (OAS) 3.0 à l'aide de Talend Cloud API Designer.

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

Les composants vous permettent de réutiliser divers éléments à travers une API. Ces éléments peuvent être des :

variables de chemins ;
paramètres de requêtes ;
en-têtes ;
réponses.

Combinaisons

Les combinaisons vous permettent de créer un type de données en combinant plusieurs autres types de données. Talend Cloud API Designer supporte deux types de 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.

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

OAS 3.0 vous permet de définir de nouveaux codes de statut pour vos opérations :

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.

Les réponses définies avec un code de statut explicite sont prioritaires sur les familles de code de statut et les réponses par défaut, les familles de code de statut ont la priorité sur les réponses par défaut. Dans l'exemple suivant :

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é

OAS 3.0 propose des nouveaux schémas de sécurité pour votre API :

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.

Cette page vous a-t-elle aidé ?

Si vous rencontrez des problèmes sur cette page ou dans son contenu – une faute de frappe, une étape manquante ou une erreur technique – dites-nous comment nous améliorer !

Laissez vos commentaires ici