Consulte os conectores compatíveis com a integração de aplicativos.

Conferir a especificação OpenAPI para sua integração

Visualização — OpenAPI Specification

Esse recurso está sujeito aos "Termos de ofertas pré-GA" na seção "Termos de Serviço gerais" dos Termos específicos de serviço. Os recursos pré-GA estão disponíveis "no estado em que se encontram" e podem ter suporte limitado. Para mais informações, consulte as descrições da fase de lançamento.

Application Integration permite gerar e visualizar dinamicamente as especificações OpenAPI das integrações publicadas que são configuradas com um ou mais gatilhos de API. Ao acessar a especificação OpenAPI da sua integração, você pode:

• Entenda completamente os endpoints, métodos e estruturas de dados da API da sua integração.
• Ofereça uma visão detalhada e centralizada da API da sua integração para permitir um desenvolvimento e solução de problemas mais eficientes.
• Exponha suas APIs de integração e integre-as perfeitamente a agentes de conversação, como os agentes de conversação do Google Cloud.

O que é a especificação do OpenAPI?

A especificação OpenAPI (OAS) é um formato padrão independente de linguagem para descrever APIs RESTful. Geralmente escrita nos formatos YAML ou JSON, a especificação da OpenAPI apresenta uma descrição formal dos elementos da API, como o URL de 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.

Observação:Application Integration só oferece suporte à versão 3.0.1 da especificação da OpenAPI.

Gerar e conferir a especificação da OpenAPI

É possível gerar e conferir dinamicamente a especificação OpenAPI das suas integrações no editor de integração no console do Google Cloud ou usando uma chamada de API.

Antes de começar

• Confirme se a integração está configurada com um ou mais acionadores de API. Para informações sobre como configurar gatilhos de API, consulte Gatilhos de API.
• Publique sua integração. Para saber como publicar uma integração, consulte Testar e publicar integrações.

Conferir a especificação OpenAPI

Para conferir a especificação OpenAPI da sua integração, selecione uma das opções:

Console

Para conferir a especificação da OpenAPI de uma integração específica, siga estas etapas:

1. Acesse a página Application Integration.

   Acessar o Application Integration

2. No menu de navegação, clique em Integrações.

   A página Integrações aparece, listando todas as integrações disponíveis no projeto Google Cloud .

3. Clique na integração em que você quer conferir a especificação OpenAPI. Isso abre a integração no editor de integração.
4. Clique em (menu "Ações") na barra de ferramentas do editor de integração e selecione Ver especificação da OpenAPI.

   O painel View OpenAPI spec aparece mostrando a especificação da OpenAPI da integração. A especificação OpenAPI gerada contém, por padrão, todos os acionadores de API configurados na integração.

   • Para conferir a especificação OpenAPI de um gatilho específico, selecione-o na lista suspensa APIs.
   • Para fazer o download da especificação da OpenAPI como um arquivo YAML, clique em fazer o download .

Observação:só é possível visualizar e fazer o download da especificação OpenAPI, no formato YAML, para uma única integração no editor de integração por vez. Para conferir e fazer o download da especificação da OpenAPI nos formatos YAML ou JSON, siga as instruções na seção API.

API

O método generateOpenApiSpec da API Application Integration permite que você visualize a especificação OpenAPI da integração usando uma chamada de API.

Use o comando curl a seguir para conferir a especificação da OpenAPI de uma ou mais integrações na mesma região:

Dica:o curl geralmente vem pré-instalado nos sistemas operacionais Linux e macOS. Caso não tenha o curl, faça o download na página de versões e downloads do curl.

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/integrations/-:generateOpenApiSpec"
          

Substitua:

• TRIGGER_NAME, TRIGGER_NAME_2, TRIGGER_NAME_n: os nomes do acionador da API na integração em que você quer conferir a especificação OpenAPI.
• INTEGRATION_NAME: o nome da integração.
• DOC_TYPE: o tipo de documento a ser gerado. Os seguintes valores são aceitos: YAML ou JSON.
• PROJECT_ID: o ID do seu projeto do Google Cloud .
• LOCATION: o local do seu projeto do Google Cloud .
  Observação:só é possível visualizar a especificação OpenAPI para várias integrações na mesma região.

Como entender a especificação OpenAPI

Application Integration gera a especificação OpenAPI para suas integrações publicadas seguindo o padrão OpenAPI Specification 3.0. A tabela a seguir descreve os elementos da especificação OpenAPI gerada na 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 acionador 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 acionador de API correspondente. Observação:no momento, Application Integration oferece suporte apenas a um conjunto limitado de palavras-chave do esquema JSON. Para saber mais sobre as palavras-chave compatíveis, consulte Considerações.
components	O campo schemas contém o esquema JSON para as variáveis de entrada e saída do acionador da API. O campo securitySchemes contém as informações de autenticação dos acionadores da API.

Considerações

As considerações a seguir 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 acionadores de API.
• A especificação da OpenAPI é gerada apenas para integrações na mesma região.
• A especificação OpenAPI é gerada no formato YAML por padrão. Para gerar e conferir a especificação da OpenAPI no formato JSON, defina o parâmetro fileFormat como JSON na chamada da API.
• No momento, Application Integration oferece suporte apenas ao 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.