Prise en charge d’OpenAPI dans l’étape REST

  • Rversion finale: Xanadu
  • Mis à jour 1 août 2024
  • 4 minutes de lecture

    • Renseignez les champs d'étape REST et les entrées d'action avec les informations importées à partir d'une spécification OpenAPI. Importez les spécifications en fournissant une URL au YAML ou au JSON, ou en copiant et collant du contenu.

    Avantages

    La prise en charge d’OpenAPI dans l’étape REST offre ces avantages.

    • Utilisez des informations importées à partir d’une spécification OpenAPI pour configurer les opérations de l’étape REST, les méthodes HTTP, les paramètres, le corps de la demande, le chemin d’accès et les en-têtes.
    • Examinez les opérations d’API disponibles sans quitter l’interface du Concepteur de flux.
    • Générez les entrées nécessaires à l’étape REST pour envoyer des demandes valides à un service OpenAPI et ajoutez-les à l’étape REST à l’emplacement approprié.
    Remarque :
    Consultez toujours les valeurs d’étape REST importées à partir d’une spécification OpenAPI avant d’envoyer une demande. Supprimez les paramètres, les en-têtes et les entrées dont l’API ne requiert pas.

    Entrées générées

    Lorsque vous importez une spécification OpenAPI, le système crée toutes les entrées requises et les ajoute au formulaire Étape REST le cas échéant. Lors de l’exécution, le système envoie une demande REST qui contient les valeurs d’entrée fournies à l’action. Par exemple, si une API nécessite la transmission d’un paramètre name dans la demande, le système crée une entrée name et l’ajoute à l’étape REST. Lorsque vous ajoutez l’action au flux, le nom devient une entrée de l’action.

    Le système mappe les types de données OpenAPI aux Studio de workflow types de données. Par exemple, si la spécification OpenAPI nécessite un objet utilisateur, le système crée un objet de données complexe comme entrée. Pour plus d’informations, reportez-vous à la rubrique Données complexes.

    Limite de taille de la spécification

    Par défaut, le système peut importer des spécifications OpenAPI jusqu’à 10 Mo. Pour augmenter la taille de l’importation, mettez à jour la glide.rest.openapi.max_request_size propriété système. La valeur maximale est de 100 Mo.

    Gestion des spécifications

    Importez une spécification OpenAPI en sélectionnant des options à l’étape REST. Pour plus d'informations, consultez Étape REST. L’importation d’une spécification OpenAPI crée un enregistrement dans la table OpenAPI [sys_openapi]. Vous pouvez afficher ou supprimer des enregistrements de spécifications directement à partir de cette table. Pour mettre à jour une spécification, supprimez-la et importez-la à nouveau.

    Considérations relatives à la conception

    Créez une étape REST à partir d’une spécification OpenAPI en gardant ces considérations à l’esprit.

    Supprimer les paramètres d’étape REST inutiles
    lors de l'importation d'une spécification OpenAPI, le système ajoute tous les paramètres et en-têtes présents dans la spécification à l'étape REST. Passez en revue les valeurs de l'étape REST finale et supprimez les paramètres que vous ne souhaitez pas envoyer dans la demande. Par exemple, si l'API accepte les en-têtes de type de contenu pour les formats JSON et XML, le système ajoute les deux en-têtes à l'étape REST. Supprimez l'un des en-têtes en fonction du type de contenu que vous souhaitez recevoir dans la réponse.
    Rendre les étiquettes d’entrée conviviales
    Assurez-vous que les étiquettes d’entrée requises pour l’étape REST sont claires et compréhensibles. Effacer les étiquettes permet aux concepteurs de flux de comprendre facilement les entrées requises lors de l’utilisation de l’action dans un flux.
    Supprimer les entrées qui ne nécessitent pas la configuration de Flow Designer
    Lors de l’importation d’une spécification OpenAPI, le système ajoute toutes les entrées présentes dans la spécification à la section d’entrée d’action. Supprimez toutes les entrées qui ne nécessitent pas l’intervention d’un concepteur de flux pour leur configuration. Par exemple, si une variable d’étape REST reçoit une valeur d’une autre étape de l’action, une entrée d’action n’est pas requise.
    Éviter de modifier le fonctionnement de l’API
    La modification de la valeur du champ Opération API supprime toutes les valeurs dépendantes de cette opération. Si vous configurez les valeurs de spécification OpenAPI dans le formulaire Étape REST, puis que vous modifiez l’opération, le système n’enregistre pas votre configuration. Les valeurs saisies manuellement par un utilisateur ne sont pas affectées.

    Limitations

    Créez une étape REST à partir d’une spécification OpenAPI avec ces limitations.

    Types de médias de corps de demande
    Le corps de la demande ne prend en charge que les types de médias JSON et XML. Si l’opération sélectionnée à partir de la spécification OpenAPI importée contient un corps de demande avec un type de média différent, le système ajoute une pastille de données de type Chaîne au champ Corps de la demande .
    Composants OpenAPI 3.0

    OpenAPI 3.0 ajoute de nouveaux composants à Swagger 2.0 pour décrire une API plus en détail. La prise en charge d’OpenAPI à l’étape REST prend en charge certains de ces composants, mais pas tous. L’étape REST ne prend actuellement pas en charge ces composants.

    • Objet de schéma : propriétés oneOf, anyOf
    • Objet discriminant
    • Objet d’informations : termsOfService, contact, champs de licence
    • Exemple d’objet
    • Objet de lien
    • Objet de rappel
    • Objet du schéma de sécurité
    • Objet des besoins de Security
    • Objet de balise
    • Objet de documentation externe
    • Objet serveur
    • Extensions de spécifications
    • Références récursives

    Plus d’informations sur ces composants sont disponibles dans la documentation OpenAPI. Voir Spécification OpenAPI.