Afficher la spécification OpenAPI de votre intégration

Application Integration vous permet de générer et d'afficher de manière dynamique les spécifications OpenAPI de vos intégrations publiées qui sont 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 :

• Comprenez parfaitement les points de terminaison, les méthodes et les structures de données de l'API de votre intégration.
• Améliorez 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.
• Exposez vos API d'intégration et intégrez-les facilement à des agents conversationnels. 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 contenus, ses modèles de requête et de réponse, etc. Pour en savoir plus sur la spécification OpenAPI, consultez Spécification OpenAPI.

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

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

Vous pouvez générer et afficher de manière dynamique la spécification OpenAPI pour vos intégrations à partir de l'éditeur d'intégrations dans la console Google Cloud 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 savoir comment publier 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 liste toutes les intégrations disponibles dans le projet Google Cloud .

3. Cliquez sur l'intégration pour laquelle vous souhaitez afficher la spécification OpenAPI. Cela entraîne l'ouverture de l'intégration dans l'éditeur d'intégrations.
4. Cliquez sur (menu d'actions) dans la barre d'outils de l'éditeur d'intégrations, puis sélectionnez Afficher la spécification OpenAPI.

   Le volet Afficher la spécification OpenAPI s'affiche, avec 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 sous forme de fichier 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 depuis l'éditeur d'intégrations. 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 :

Remarque : curl est généralement préinstallé sur les systèmes d'exploitation Linux et macOS. Si vous ne disposez pas de curl, vous pouvez le télécharger depuis la page des versions et des 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 : nom du déclencheur d'API dans votre intégration pour lequel 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 projet Google Cloud .
• LOCATION : emplacement de votre projet Google Cloud .
  Remarque : Vous ne pouvez afficher la spécification OpenAPI que pour plusieurs intégrations de 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 OpenAPI Specification 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 d'accès sont créés pour chaque déclencheur d'API sélectionné dans l'intégration. L'URL du serveur combinée au chemin d'accès 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 acceptés, consultez Remarques.
components	Le champ schemas contient le schéma JSON des 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 considérations suivantes s'appliquent lors de l'affichage de la spécification OpenAPI pour 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 de 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 suivant :
  • type
  • items
  • properties
  • description
  • required
  • array
  • object
  • oneOf
  • allOf
  • anyOf
  • not
  • null
  • enum
  • additionalProperties
  • default
• Lors de la validation de la spécification OpenAPI à l'aide de l'éditeur Swagger, vous pouvez rencontrer des erreurs sémantiques liées aux chemins d'accès de l'API, semblables à l'image suivante :

  

  Vous pouvez ignorer ces erreurs. La spécification OpenAPI est toujours valide.

Étapes suivantes

• Créer des agents conversationnels avec Application Integration
• En savoir plus sur les déclencheurs d'API
• Découvrez comment tester et publier des intégrations.