Cómo ver la especificación de OpenAPI de tu integración
Application Integration permite generar y ver de forma dinámica las especificaciones de OpenAPI de tus integraciones publicadas que están configuradas con uno o más activadores de API. Acceder a la especificación de OpenAPI de tu integración te permite hacer lo siguiente:
Obtén una comprensión integral de los extremos de la API, los métodos y las estructuras de datos de tu integración.
Proporciona una vista detallada y centralizada de la API de tu integración para permitir un desarrollo y una solución de problemas más eficientes.
La especificación de OpenAPI (OAS) es un formato estándar independiente del lenguaje para describir las APIs de RESTful. La especificación de OpenAPI, que suele escribirse en formatos YAML o JSON, presenta una descripción formal de los elementos de la API, como su URL base, las rutas y verbos, los encabezados, los parámetros de consulta, los tipos de contenido, los modelos de solicitud y respuesta, y mucho más. Para obtener más información sobre la Especificación de OpenAPI, consulta Especificación de OpenAPI.
Genera y visualiza la especificación de OpenAPI
Puedes generar y ver de forma dinámica la especificación de OpenAPI para tus integraciones desde el editor de integraciones en la consola de Google Cloud o con una llamada a la API.
Antes de comenzar
Confirma que tu integración esté configurada con uno o más activadores de API. Para obtener información sobre cómo configurar activadores de API, consulta Activadores de API.
Publica tu integración. Para obtener información sobre cómo publicar una integración, consulta Prueba y publica integraciones.
Ver la especificación de OpenAPI
Para ver la especificación de OpenAPI de tu integración, selecciona una de las siguientes opciones:
Application Integration genera la especificación de OpenAPI para tus integraciones publicadas según el estándar de la especificación de OpenAPI 3.0. En la siguiente tabla, se describen los elementos de la especificación de OpenAPI que se generan en Application Integration:
Elemento
Descripción
openapi
Es la versión de la especificación de OpenAPI que se usa.
info
Es la información sobre la integración, como su nombre (título), descripción y versión publicada.
servers
Son las URLs del servidor que alojan la integración.
paths
Se crean rutas de acceso para cada activador de API seleccionado en la integración. La URL del servidor combinada con la ruta constituye el extremo de API para realizar llamadas a la API.
Los campos Request y Response se completan según las variables de entrada y salida configuradas para el activador de API correspondiente.
components
El campo schemas contiene el esquema JSON para las variables de entrada y salida del activador de la API.
El campo securitySchemes contiene la información de autenticación para los activadores de la API.
Consideraciones
Se aplican las siguientes consideraciones cuando visualizas la especificación de OpenAPI de tu integración:
La especificación de OpenAPI solo se genera para las integraciones publicadas.
La especificación de OpenAPI solo se genera para las integraciones configuradas con uno o más activadores de API.
La especificación de OpenAPI solo se genera para las integraciones en la misma región.
De forma predeterminada, la especificación de OpenAPI se genera en formato YAML. Para generar y ver la especificación de OpenAPI en formato JSON, establece el parámetro fileFormat en JSON en la llamada a la API.
Actualmente, Application Integration solo admite el siguiente conjunto limitado de palabras clave del esquema JSON:
type
items
properties
description
required
array
object
oneOf
allOf
anyOf
not
null
enum
additionalProperties
default
Cuando valides la especificación de OpenAPI con el editor de Swagger, es posible que encuentres errores semánticos relacionados con las rutas de la API, similares a los de la siguiente imagen:
Estos errores se pueden ignorar de forma segura. La especificación de OpenAPI sigue siendo válida.
[[["Fácil de comprender","easyToUnderstand","thumb-up"],["Resolvió mi problema","solvedMyProblem","thumb-up"],["Otro","otherUp","thumb-up"]],[["Difícil de entender","hardToUnderstand","thumb-down"],["Información o código de muestra incorrectos","incorrectInformationOrSampleCode","thumb-down"],["Faltan la información o los ejemplos que necesito","missingTheInformationSamplesINeed","thumb-down"],["Problema de traducción","translationIssue","thumb-down"],["Otro","otherDown","thumb-down"]],["Última actualización: 2025-08-25 (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)."]]
