Afficher la spécification OpenAPI de votre intégration

Aperçu : spécification OpenAPI

Cette fonctionnalité est soumise aux "Conditions des offres de pré-DG" de la section "Conditions générales du service" des Conditions spécifiques du service. Les fonctionnalités pré-DG sont disponibles "en l'état" et peuvent avoir une prise en charge limitée. Pour en savoir plus, consultez les descriptions des étapes de lancement.

Application Integration permet de générer et d'afficher de manière dynamique les spécifications OpenAPI de vos intégrations publiées et configurées avec un ou plusieurs déclencheurs d'API. L'accès à la spécification OpenAPI de votre intégration vous permet d'effectuer les opérations suivantes :

• Obtenir une compréhension complète des points de terminaison, des méthodes et des structures de données de l'API de votre intégration.
• Améliorer l'efficacité du développement et du dépannage en fournissant une vue détaillée et centralisée de l'API de votre intégration.
• Exposer les API de votre intégration et les intégrer de manière transparente aux agents conversationnels. Pour en savoir plus, consultez Créer des agents conversationnels avec Application Integration.

Qu'est-ce que la spécification OpenAPI ?

La spécification OpenAPI (OAS) est un format standard indépendant du langage permettant de décrire les API RESTful. Généralement écrite au format YAML ou JSON, la spécification OpenAPI présente une description formelle des éléments de l'API, tels que son URL de base, ses chemins et verbes, ses en-têtes, ses paramètres de requête, ses types de contenu, ses modèles de requête et de réponse, et plus encore. Pour en savoir plus sur la spécification OpenAPI, consultez Spécification OpenAPI.

Remarque : Application Integration n'est compatible qu'avec la spécification OpenAPI version 3.0.1.

Générer et afficher la spécification OpenAPI

Vous pouvez générer et afficher de manière dynamique la spécification OpenAPI de vos intégrations à partir de l'éditeur d'intégration dans la Google Cloud console ou à l'aide d'un appel d'API.

Avant de commencer

• Vérifiez que votre intégration est configurée avec un ou plusieurs déclencheurs d'API. Pour en savoir plus sur la configuration des déclencheurs d'API, consultez Déclencheurs d'API.
• Publiez votre intégration. Pour en savoir plus sur la publication d'une intégration, consultez Tester et publier des intégrations.

Afficher la spécification OpenAPI

Pour afficher la spécification OpenAPI de votre intégration, sélectionnez l'une des options suivantes :

Console

Pour afficher la spécification OpenAPI d'une intégration spécifique, procédez comme suit :

1. Accédez à la page Application Integration.

   Accéder à Application Integration

2. Dans le menu de navigation, cliquez sur Intégrations.

   La page Intégrations s'affiche et répertorie toutes les intégrations disponibles dans le Google Cloud projet.

3. Cliquez sur l'intégration pour laquelle vous souhaitez afficher la spécification OpenAPI. La page de l'éditeur d'intégration s'affiche.
4. Cliquez sur (menu d'actions) dans la barre d'outils de l'éditeur d'intégration, puis sélectionnez Afficher la spécification OpenAPI.

   Le volet Afficher la spécification OpenAPI s'affiche et présente la spécification OpenAPI de l'intégration. Par défaut, la spécification OpenAPI générée contient tous les déclencheurs d'API configurés dans l'intégration.

   • Pour afficher la spécification OpenAPI d'un déclencheur d'API spécifique, sélectionnez-le dans la liste déroulante API.
   • Pour télécharger la spécification OpenAPI au format YAML, cliquez sur download (Télécharger).

Remarque : Vous ne pouvez afficher et télécharger la spécification OpenAPI au format YAML que pour une seule intégration à la fois à partir de l'éditeur d'intégration. Pour afficher et télécharger la spécification OpenAPI aux formats YAML ou JSON, suivez les instructions de la section API.

API

La méthode generateOpenApiSpec de l'API Application Integration vous permet d'afficher la spécification OpenAPI de votre intégration à l'aide d'un appel d'API.

Utilisez la commande curl suivante pour afficher la spécification OpenAPI d'une ou de plusieurs intégrations dans la même région :

Astuce : curl est généralement préinstallé pour les systèmes d'exploitation Linux et macOS. Si vous ne disposez pas de curl, vous pouvez le télécharger sur la page relative aux versions et téléchargements de curl .

curl -X POST \
    -H "authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
    -d '{
    "apiTriggerResources": [{
    "integrationResource": "INTEGRATION_NAME",
    "triggerId": ["api_trigger/TRIGGER_NAME", "api_trigger/TRIGGER_NAME_2", "api_trigger/TRIGGER_NAME_n"]
    },
    {
    "integrationResource": "INTEGRATION_NAME",
      "triggerId": ["api_trigger/TRIGGER_NAME"]
    }],
    "fileFormat": "DOC_TYPE"
    }' \
    "https://LOCATION-integrations.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION:generateOpenApiSpec"
          

Remplacez les éléments suivants :

• TRIGGER_NAME, TRIGGER_NAME_2, TRIGGER_NAME_n : noms des déclencheurs d'API dans votre intégration pour lesquels vous souhaitez afficher la spécification OpenAPI.
• INTEGRATION_NAME : nom de votre intégration.
• DOC_TYPE : type de document à générer. Les valeurs suivantes sont acceptées : YAML ou JSON.
• PROJECT_ID : ID de votre Google Cloud projet.
• LOCATION : emplacement de votre Google Cloud projet.
  Remarque : Vous ne pouvez afficher la spécification OpenAPI que pour plusieurs intégrations dans la même région.

Comprendre la spécification OpenAPI

Application Integration génère la spécification OpenAPI pour vos intégrations publiées conformément à la norme de spécification OpenAPI 3.0. Le tableau suivant décrit les éléments de la spécification OpenAPI générée dans Application Integration :

Élément	Description
openapi	Version de la spécification OpenAPI utilisée.
info	Informations sur l'intégration, telles que son nom (titre), sa description et sa version publiée.
servers	URL des serveurs qui hébergent l'intégration.
paths	Des chemins sont créés pour chaque déclencheur d'API sélectionné dans l'intégration. L'URL du serveur combinée au chemin constitue le point de terminaison de l'API pour effectuer des appels d'API. Les champs Request et Response sont renseignés en fonction des variables d'entrée et de sortie configurées pour le déclencheur d'API correspondant. Remarque : Application Integration n'est actuellement compatible qu'avec un ensemble limité de mots clés de schéma JSON. Pour en savoir plus sur les mots clés compatibles, consultez Remarques.
components	Le champ schemas contient le schéma JSON pour les variables d'entrée et de sortie du déclencheur d'API. Le champ securitySchemes contient les informations d'authentification pour les déclencheurs d'API.

Remarques

Les remarques suivantes s'appliquent lorsque vous affichez la spécification OpenAPI de votre intégration :

• La spécification OpenAPI n'est générée que pour les intégrations publiées.
• La spécification OpenAPI n'est générée que pour les intégrations configurées avec un ou plusieurs déclencheurs d'API.
• La spécification OpenAPI n'est générée que pour les intégrations dans la même région.
• La spécification OpenAPI est générée au format YAML par défaut. Pour générer et afficher la spécification OpenAPI au format JSON, définissez le paramètre fileFormat sur JSON dans l'appel d'API.
• Application Integration n'est actuellement compatible qu'avec l'ensemble limité de mots clés de schéma JSON suivants :
  • type
  • items
  • properties
  • description
  • required
  • array
  • object
  • oneOf
  • allOf
  • anyOf
  • not
  • null
  • enum
  • additionalProperties
  • default
• Lorsque vous validez la spécification OpenAPI à l'aide de l'éditeur Swagger, vous pouvez rencontrer des erreurs sémantiques liées aux chemins d'API, semblables à celles de l'image suivante :

  

  Vous pouvez ignorer ces erreurs sans risque. La spécification OpenAPI reste valide.

Étape suivante

• Créer des agents conversationnels avec Application Integration.
• En savoir plus sur les déclencheurs d'API.
• En savoir plus sur les tests et la publication d'intégrations.