Application Integration permite gerar e visualizar dinamicamente as especificações OpenAPI das suas integrações publicadas que estão configuradas com um ou mais gatilhos de API. Ao acessar a especificação OpenAPI da sua integração, você pode:
Entenda os endpoints, métodos e estruturas de dados da API da sua integração.
Permite um desenvolvimento e uma solução de problemas mais eficientes ao fornecer uma visão detalhada e centralizada da API da sua integração.
A especificação OpenAPI (OAS, na sigla em inglês) é um formato padrão e independente de linguagem para descrever APIs RESTful. Normalmente escrita em formatos YAML ou JSON, a especificação OpenAPI apresenta uma descrição formal dos elementos da API, como URL base, caminhos e verbos, cabeçalhos, parâmetros de consulta, tipos de conteúdo, modelos de solicitação e resposta e muito mais. Para mais informações sobre a especificação OpenAPI, consulte Especificação OpenAPI.
Gerar e visualizar a especificação OpenAPI
É possível gerar e visualizar dinamicamente a especificação OpenAPI das suas integrações no editor de integração do console Google Cloud ou usando uma chamada de API.
Antes de começar
Confirme se a integração está configurada com um ou mais gatilhos de API. Para informações sobre como configurar gatilhos de API, consulte Gatilhos de API.
Application Integration gera a especificação OpenAPI para suas integrações publicadas de acordo com o padrão OpenAPI Specification 3.0. A tabela a seguir descreve os elementos da especificação OpenAPI gerados no Application Integration:
Elemento
Descrição
openapi
A versão da especificação OpenAPI usada.
info
Informações sobre a integração, como nome (título), descrição e versão publicada.
servers
Os URLs do servidor que hospedam a integração.
paths
Os caminhos são criados para cada gatilho de API selecionado na integração. O URL do servidor combinado com o caminho constitui o endpoint de API para fazer chamadas de API.
Os campos Request e Response são preenchidos com base nas variáveis de entrada e saída configuradas para o gatilho de API correspondente.
components
O campo schemas contém o esquema JSON para as variáveis de entrada e saída do gatilho da API.
O campo securitySchemes contém as informações de autenticação dos gatilhos de API.
Considerações
As seguintes considerações se aplicam ao visualizar a especificação OpenAPI da sua integração:
A especificação OpenAPI é gerada apenas para integrações publicadas.
A especificação OpenAPI é gerada apenas para integrações configuradas com um ou mais gatilhos de API.
A especificação OpenAPI é gerada apenas para integrações na mesma região.
A especificação OpenAPI é gerada no formato YAML por padrão. Para gerar e visualizar a especificação OpenAPI no formato JSON, defina o parâmetro fileFormat como JSON na chamada de API.
No momento, Application Integration é compatível apenas com o seguinte conjunto limitado de palavras-chave do esquema JSON:
type
items
properties
description
required
array
object
oneOf
allOf
anyOf
not
null
enum
additionalProperties
default
Ao validar a especificação OpenAPI usando o Swagger Editor, você pode encontrar erros semânticos relacionados aos caminhos da API, semelhantes à imagem a seguir:
Esses erros podem ser ignorados com segurança. A especificação OpenAPI ainda é válida.
[[["Fácil de entender","easyToUnderstand","thumb-up"],["Meu problema foi resolvido","solvedMyProblem","thumb-up"],["Outro","otherUp","thumb-up"]],[["Difícil de entender","hardToUnderstand","thumb-down"],["Informações incorretas ou exemplo de código","incorrectInformationOrSampleCode","thumb-down"],["Não contém as informações/amostras de que eu preciso","missingTheInformationSamplesINeed","thumb-down"],["Problema na tradução","translationIssue","thumb-down"],["Outro","otherDown","thumb-down"]],["Última atualização 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)."]]
