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

  • Rversion finale: Washingtondc
  • Mis à jour 1 févr. 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 à l’étape REST offre les avantages suivants.

    • 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 du Concepteur de flux.
    • Générez les entrées requises pour que l’étape REST envoie des demandes valides à un service OpenAPI et ajoutez-les à l’étape REST à l’emplacement approprié.
    Remarque :
    Vérifiez 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 É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 de nom 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 aux types de Concepteur de flux 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 section Données complexes.

    Limite de taille de 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 OpenAPIs [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 lors de l’utilisation de l’action dans un flux.
    Supprimer les entrées qui ne nécessitent pas de 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 la configuration d’un concepteur de flux. Par exemple, si une variable Étape REST reçoit une valeur d’une autre étape de l’action, aucune entrée d’action n’est requise.
    Éviter de modifier le fonctionnement de l’API
    La modification de la valeur du champ Opération API supprime toutes les valeurs qui dépendent de cette opération. Si vous configurez les valeurs de spécification OpenAPI dans le formulaire É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 du corps de la 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 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 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 de 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. Reportez-vous à la section Spécification OpenAPI.