Cómo ver la especificación de OpenAPI de tu integración

Versión preliminar : Especificación de OpenAPI

Esta función está sujeta a las "Condiciones de la oferta previa a la DG" en la sección Condiciones Generales del Servicio de las Condiciones Específicas del Servicio. Las funciones de la fase previa a la DG están disponibles “sin modificaciones” y pueden tener asistencia limitada. Para obtener más información, consulta las descripciones de la etapa de lanzamiento.

Application Integration proporciona la capacidad de 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:

• Obtener una comprensión integral de los extremos, los métodos y las estructuras de datos de la API de tu integración
• Proporcionar 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
• Exponer las APIs de tu integración y realizar una integración sin problemas con los agentes conversacionales. Consulta Cómo compilar agentes conversacionales con Application Integration.

¿Qué es la especificación de OpenAPI?

La especificación de OpenAPI (OAS) es un formato estándar e independiente del lenguaje para describir las APIs de RESTful. Por lo general, se escribe en formatos YAML o JSON. La especificación de OpenAPI 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.

Nota: Application Integration solo admite la versión 3.0.1 de la especificación de OpenAPI.

Cómo generar y ver la especificación de OpenAPI

Puedes generar y ver de forma dinámica la especificación de OpenAPI de tus integraciones desde el editor de integración en la Google Cloud consola o mediante 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.

Cómo ver la 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 Integrations.

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

3. Haz clic en la integración para la que deseas ver la especificación de OpenAPI. Esto abrirá la integración en el 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 , en el que se muestra 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).

Nota: Solo puedes ver y descargar la especificación de OpenAPI, en formato YAML, para una sola integración desde el editor de integración a la vez. Para ver y descargar la especificación de OpenAPI, en formatos YAML o JSON, sigue las instrucciones de la sección API.

API

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

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

Nota: Por lo general, curl viene preinstalado para los sistemas operativos Linux y macOS. Si no tienes curl, puedes descargarlo de la página de curl actualizaciones y descargas.

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: Los nombres del activador de API en tu integración para los que deseas ver la especificación de OpenAPI.
• INTEGRATION_NAME: El nombre de tu integración.
• DOC_TYPE: El tipo de documento que se generará. Se admiten los siguientes valores: YAML o JSON.
• PROJECT_ID: El ID de tu Google Cloud proyecto.
• LOCATION: La ubicación de tu Google Cloud proyecto.
  Nota: Solo puedes ver la especificación de OpenAPI para varias integraciones en la misma región.

Información sobre 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	La versión de la especificación de OpenAPI que se usó
info	Información sobre la integración, como su nombre (título), descripción y versión publicada
servers	Las URLs del servidor que alojan 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 propagan según las variables de entrada y salida configuradas para el activador de API correspondiente. Nota: Actualmente, Application Integration solo admite un conjunto limitado de palabras clave del esquema JSON. Para obtener información sobre las palabras clave admitidas, consulta Consideraciones.
components	El campo schemas contiene el esquema JSON para las variables de entrada y salida del activador de API. El campo securitySchemes contiene la información de autenticación para los activadores de API.

Consideraciones

Se aplican las siguientes consideraciones cuando se ve 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.
• 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, configura 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 la siguiente imagen:

  

  Estos errores se pueden ignorar de forma segura. La especificación de OpenAPI sigue siendo válida.

¿Qué sigue?

• Cómo compilar agentes conversacionales con Application Integration.
• Información sobre los activadores de API
• Información sobre cómo probar y publicar integraciones.