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

  • Rversion finale: Yokohama
  • Mis à jour 30 janv. 2025
  • 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 à l’étape REST offre ces avantages.

    • Utilisez les informations importées à partir d’une spécification OpenAPI pour configurer les opérations d’é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 de Concepteur de flux.
    • Générez les entrées requises pour l’étape REST afin d’envoyer des demandes valides à un service OpenAPI et ajoutez-les à l’étape REST au bon emplacement.
    Remarque :
    Examinez 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 n’a pas besoin.

    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 d’é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 un paramètre de nom transmis dans la demande, le système crée une entrée de nom 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 entre les 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, consultez 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 d’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 dans 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écification 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. Les étiquettes claires permettent aux concepteurs de flux de comprendre facilement les entrées requises lorsqu’ils utilisent l’action dans un flux.
    Supprimer les entrées qui ne nécessitent pas de configuration de Concepteur de flux
    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 de conception de flux pour être configurées. 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 d’API supprime toutes les valeurs dépendantes de cette opération. Si vous configurez les valeurs de spécification OpenAPI dans le formulaire d’étape REST, puis 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 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 dans le 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 dans 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 discriminateur
    • 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 sécurité
    • 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. Consultez la spécification OpenAPI.