Visualiza la especificación de OpenAPI para tu integración

Application Integration ofrece la capacidad de generar y ver de forma dinámica las especificaciones de OpenAPI de tus integraciones publicadas que se configuran con uno o más activadores de API. Acceder a la especificación de OpenAPI de tu integración te permite hacer lo siguiente:

  • Comprende de forma integral los endpoints de API, los métodos y las estructuras de datos de tu integración.
  • Habilita un desarrollo y una solución de problemas más eficientes proporcionando una vista detallada y centralizada de la API de tu integración.
  • Expón tus APIs de integración y conéctalas sin problemas con agentes conversacionales. Consulta Crea agentes conversacionales con Application Integration.

¿Qué es la especificación de OpenAPI?

Logotipo de OpenAPI Specification

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 formato YAML o JSON, presenta una descripción formal de los elementos de la API, como su URL base, rutas y verbos, encabezados, parámetros de consulta, tipos de contenido, 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 especificación de OpenAPI

Para ver la especificación de OpenAPI de tu integración, selecciona una de las siguientes opciones:

Console

Para ver la especificación de OpenAPI de una integración específica, sigue estos pasos:

  1. Ve a la página Application Integration.

    Ir a Application Integration

  2. En el menú de navegación, haz clic en Integraciones.

    Aparecerá la página Integraciones, en la que se enumeran todas las integraciones disponibles en el proyecto de Google Cloud .

  3. Haz clic en la integración para la que deseas ver la especificación de OpenAPI. Esto abrirá la integración en la página del editor de integración.
  4. Haz clic en (menú de acciones) en la barra de herramientas del editor de integración y selecciona Ver especificación de OpenAPI.

    Aparecerá el panel Ver especificación de OpenAPI con la especificación de OpenAPI de la integración. De forma predeterminada, la especificación de OpenAPI generada contiene todos los activadores de API configurados en la integración.

    • Para ver la especificación de OpenAPI de un activador de API específico, selecciona el activador de API en la lista desplegable APIs.
    • Para descargar la especificación de OpenAPI como un archivo YAML, haz clic en download (Descargar).

API

El método generateOpenApiSpec de la API de Application Integration te permite ver la especificación de OpenAPI para tu integración con una llamada a la API.

Usa el siguiente comando curl para ver la especificación de OpenAPI de una o más integraciones en la misma región:

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"

Reemplaza lo siguiente:

  • TRIGGER_NAME, TRIGGER_NAME_2, TRIGGER_NAME_n: Son los nombres del activador de la API en tu integración para la que deseas ver la especificación de OpenAPI.
  • INTEGRATION_NAME: Es el nombre de tu integración.
  • DOC_TYPE: Es el tipo de documento que se generará. Se admiten los siguientes valores: YAML o JSON.
  • PROJECT_ID: Es el ID del proyecto de Google Cloud .
  • LOCATION: Es la ubicación de tu proyecto de Google Cloud .

Comprende la especificación de OpenAPI

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 generada en Application Integration:

Elemento Descripción
openapi Es la versión de la especificación de OpenAPI que se usa.
info Información sobre la integración, como su nombre (título), descripción y versión publicada.
servers Son las URLs del servidor que aloja la integración.
paths Se crean rutas 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 de los activadores de la API.

Consideraciones

Ten en cuenta las siguientes consideraciones cuando veas la especificación de OpenAPI para tu integración:

  • La especificación de OpenAPI solo se genera para las integraciones publicadas.
  • La especificación de OpenAPI se genera solo para las integraciones configuradas con uno o más activadores de API.
  • La especificación de OpenAPI se genera solo para las integraciones en la misma región.
  • La especificación de OpenAPI se genera en formato YAML de forma predeterminada. 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.
  • Por el momento, 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 validas 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 la siguiente imagen:

    Swagger Editor Swagger Editor

    Puedes ignorar estos errores sin problemas. La especificación de OpenAPI sigue siendo válida.

¿Qué sigue?