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 et configurées avec un ou plusieurs déclencheurs d'API. Accéder à la spécification OpenAPI de votre intégration vous permet de :
Comprenez en détail les points de terminaison, les méthodes et les structures de données de l'API de votre intégration.
Développez et résolvez les problèmes plus efficacement en obtenant une vue détaillée et centralisée de l'API de votre intégration.
La spécification OpenAPI (OAS) est un format standard et indépendant du langage permettant de décrire les API RESTful. Généralement rédigée 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, etc. Pour en savoir plus sur la spécification OpenAPI, consultez 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 de vos intégrations à partir de l'éditeur d'intégration 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.
Application Integration génère la spécification OpenAPI pour vos intégrations publiées en suivant la norme OpenAPI Specification 3.0. Le tableau suivant décrit les éléments de la spécification OpenAPI générés dans Application Integration :
Élément
Description
openapi
Version de la spécification OpenAPI utilisée.
info
Informations sur l'intégration, comme 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.
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 considérations suivantes s'appliquent lorsque vous consultez 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.
L'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
Lorsque vous validez la spécification OpenAPI à l'aide de Swagger Editor, vous pouvez rencontrer des erreurs sémantiques liées aux chemins d'accès de l'API, comme illustré dans l'image suivante :
Vous pouvez ignorer ces erreurs sans problème. La spécification OpenAPI est toujours valide.
Sauf indication contraire, le contenu de cette page est régi par une licence Creative Commons Attribution 4.0, et les échantillons de code sont régis par une licence Apache 2.0. Pour en savoir plus, consultez les Règles du site Google Developers. Java est une marque déposée d'Oracle et/ou de ses sociétés affiliées.
Dernière mise à jour le 2025/09/03 (UTC).
[[["Facile à comprendre","easyToUnderstand","thumb-up"],["J'ai pu résoudre mon problème","solvedMyProblem","thumb-up"],["Autre","otherUp","thumb-up"]],[["Difficile à comprendre","hardToUnderstand","thumb-down"],["Informations ou exemple de code incorrects","incorrectInformationOrSampleCode","thumb-down"],["Il n'y a pas l'information/les exemples dont j'ai besoin","missingTheInformationSamplesINeed","thumb-down"],["Problème de traduction","translationIssue","thumb-down"],["Autre","otherDown","thumb-down"]],["Dernière mise à jour le 2025/09/03 (UTC)."],[[["\u003cp\u003eApplication Integration allows users to dynamically generate and view OpenAPI Specifications for published integrations that include API triggers.\u003c/p\u003e\n"],["\u003cp\u003eThe OpenAPI Specification provides a comprehensive overview of an integration's API endpoints, methods, and data structures, which aids in development, troubleshooting, and integration with conversational agents.\u003c/p\u003e\n"],["\u003cp\u003eYou can view the OpenAPI Specification through the Google Cloud console's Integration editor or by using an API call with the \u003ccode\u003egenerateOpenApiSpec\u003c/code\u003e method, and both YAML and JSON formats are supported.\u003c/p\u003e\n"],["\u003cp\u003eThe generated OpenAPI Specification follows the OpenAPI Specification 3.0 standard, detailing elements such as \u003ccode\u003eopenapi\u003c/code\u003e, \u003ccode\u003einfo\u003c/code\u003e, \u003ccode\u003eservers\u003c/code\u003e, \u003ccode\u003epaths\u003c/code\u003e, and \u003ccode\u003ecomponents\u003c/code\u003e, but it only supports a limited subset of JSON schema keywords.\u003c/p\u003e\n"],["\u003cp\u003eThe specification is only generated for published integrations that have one or more API triggers, and only for integrations in the same region.\u003c/p\u003e\n"]]],[],null,["# View OpenAPI Specification for your integration\n\nSee the [supported connectors](/integration-connectors/docs/connector-reference-overview) for Application Integration.\n\nView OpenAPI Specification for your integration\n===============================================\n\n|\n| **Preview\n| --- OpenAPI Specification**\n|\n|\n| This feature is subject to the \"Pre-GA Offerings Terms\" in the General Service Terms section\n| of the [Service Specific Terms](/terms/service-terms#1).\n|\n| Pre-GA features are available \"as is\" and might have limited support.\n|\n| For more information, see the\n| [launch stage descriptions](/products#product-launch-stages).\n\n\nApplication Integration provides the ability to dynamically generate and view the OpenAPI Specifications of your published integrations that are configured with one or more [API triggers](/application-integration/docs/configure-api-trigger). Accessing the OpenAPI Specification of your integration allows you to:\n\n- Gain a comprehensive understanding of your integration's API endpoints, methods, and data structures.\n- Enable more efficient development and troubleshooting by providing a detailed and centralized view of your integration's API.\n- Expose your integration APIs and seamlessly integrate with conversational agents, see [Build conversational agents with Application Integration](/application-integration/docs/conversational-agents).\n\n\u003cbr /\u003e\n\nWhat is the OpenAPI Specification?\n----------------------------------\n\n\nThe OpenAPI Specification (OAS) is a standard, language-independent format to describe RESTful APIs. Commonly written in either YAML or JSON formats, the OpenAPI Specification presents a formal description of the API elements such as its base URL, paths and verbs, headers, query parameters, content types, request and response models, and more. For more information about the OpenAPI Specification, see [OpenAPI Specification](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.0.md).\n| **Note:** Application Integration only supports OpenAPI Specification **version 3.0.1**.\n\nGenerate and view the OpenAPI Specification\n-------------------------------------------\n\nYou can dynamically generate and view the OpenAPI Specification for your integrations from the Integration editor in the Google Cloud console or using an API call.\n\n### Before you begin\n\n- Confirm that your integration is configured with one or more API triggers. For information about configuring API triggers, see [API triggers](/application-integration/docs/configure-api-trigger).\n- Publish your integration. For information about how to publish an integration, see [Test and publish integrations](/application-integration/docs/test-publish-integrations).\n\n### View OpenAPI Specification\n\n\nTo view the OpenAPI Specification for your integration, select one of the options: \n\n### Console\n\nTo view the OpenAPI Specification for a specific integration, do the following steps:\n\n1. Go to the **Application Integration** page.\n\n [Go to Application Integration](https://console.cloud.google.com/integrations)\n2. In the navigation menu, click **Integrations** .\n\n\n The **Integrations** page appears, listing all the integrations available in the Google Cloud project.\n3. Click the integration for which you want to view the OpenAPI Specification. This opens the integration in the Integration editor.\n4. Click the more_vert (Actions menu) in the Integration editor toolbar, and select **View OpenAPI spec** .\n\n The **View OpenAPI spec** pane appears displaying the OpenAPI Specification of the integration. The generated OpenAPI Specification, by default, contains all the API triggers configured in the integration.\n - To view the OpenAPI Specification for a specific API trigger, select the API trigger from the **APIs** drop-down list.\n - To download the OpenAPI Specification as a YAML file, click download (Download).\n\n \u003cbr /\u003e\n\n| **Note:** You can only view and download the OpenAPI Specification, in YAML format, for a single integration from the Integration editor at a time. To view and download the OpenAPI Specification, in YAML or JSON formats, follow the instructions in the **API** section.\n\n### API\n\nThe `generateOpenApiSpec` method of the Application Integration API allows you to view the OpenAPI Specification for your integration using an API call.\n\nUse the following `curl` command to view the OpenAPI Specification for one or more integrations in the same region:\n**Tip:** `curl` typically comes pre-installed for Linux and macOS operating systems. If you don't have `curl`, you can download it from the `curl` [releases and downloads page](https://curl.haxx.se/download.html). \n\n```\ncurl -X POST \\\n -H \"authorization: Bearer $(gcloud auth print-access-token)\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"apiTriggerResources\": [{\n \"integrationResource\": \"INTEGRATION_NAME\",\n \"triggerId\": [\"api_trigger/TRIGGER_NAME\", \"api_trigger/TRIGGER_NAME_2\", \"api_trigger/TRIGGER_NAME_n\"]\n },\n {\n \"integrationResource\": \"INTEGRATION_NAME\",\n \"triggerId\": [\"api_trigger/TRIGGER_NAME\"]\n }],\n \"fileFormat\": \"DOC_TYPE\"\n }' \\\n \"https://LOCATION-integrations.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION:generateOpenApiSpec\"\n \n```\n\n\nReplace the following:\n\n- \u003cvar translate=\"no\"\u003eTRIGGER_NAME\u003c/var\u003e`, `\u003cvar translate=\"no\"\u003eTRIGGER_NAME_2\u003c/var\u003e`, `\u003cvar translate=\"no\"\u003eTRIGGER_NAME_n\u003c/var\u003e: The names of the API trigger in your integration which you want to view the OpenAPI Specification for.\n- \u003cvar translate=\"no\"\u003eINTEGRATION_NAME\u003c/var\u003e: The name of your integration.\n- \u003cvar translate=\"no\"\u003eDOC_TYPE\u003c/var\u003e: The type of document to generate. The following values are supported: `YAML` or `JSON`.\n- \u003cvar translate=\"no\"\u003ePROJECT_ID\u003c/var\u003e: The ID of your Google Cloud project.\n- \u003cvar translate=\"no\"\u003eLOCATION\u003c/var\u003e: The location of your Google Cloud project. **Note:** You can only view the OpenAPI Specification for multiple integrations in the same region.\n\n\u003cbr /\u003e\n\nUnderstanding the OpenAPI Specification\n---------------------------------------\n\n\nApplication Integration generates the OpenAPI Specification for your published integrations following the [OpenAPI Specification 3.0](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.0.md) standard. The following table describes the elements of the OpenAPI Specification generated in Application Integration:\n\n\u003cbr /\u003e\n\nConsiderations\n--------------\n\n\nThe following considerations apply when viewing the OpenAPI Specification for your integration:\n\n- The OpenAPI Specification is generated only for published integrations.\n- The OpenAPI Specification is generated only for integrations configured with one or more API triggers.\n- The OpenAPI Specification is generated only for integrations in the same region.\n- The OpenAPI Specification is generated in YAML format by default. To generate and view the OpenAPI Specification in JSON format, set the `fileFormat` parameter to `JSON` in the API call.\n- Application Integration currently supports only the following limited set of JSON schema keywords:\n - `type`\n - `items`\n - `properties`\n - `description`\n - `required`\n - `array`\n - `object`\n - `oneOf`\n - `allOf`\n - `anyOf`\n - `not`\n - `null`\n - `enum`\n - `additionalProperties`\n - `default`\n- When validating the OpenAPI specification using the [Swagger Editor](https://editor.swagger.io/), you may encounter semantic errors related to the API paths similar to the following image:\n\n\n These errors can be safely ignored. The OpenAPI Specification is still valid.\n\nWhat's next\n-----------\n\n- [Build conversational agents with Application Integration](/application-integration/docs/conversational-agents).\n- Learn about [API triggers](/application-integration/docs/configure-api-trigger).\n- Learn about [Test and publish integrations](/application-integration/docs/test-publish-integrations)."]]
