Ver a especificação OpenAPI da integração

Visualização — especificação OpenAPI

Este recurso está sujeito aos Termos das Soluções Pré-GA na seção Termos Gerais de Serviço 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.

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

• Ter uma compreensão abrangente dos endpoints, métodos e estruturas de dados da API da integração.
• Permitir um desenvolvimento e solução de problemas mais eficientes, fornecendo uma visualização detalhada e centralizada da API da integração.
• Expor as APIs de integração e integrar perfeitamente com agentes de conversação. Consulte Criar agentes de conversação com o Application Integration.

O que é a especificação do OpenAPI?

A especificação OpenAPI (OAS, na sigla em inglês) é um formato padrão independente de linguagem para descrever APIs RESTful. Geralmente escrita nos 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.

Observação:o Application Integration oferece suporte apenas à especificação OpenAPI versão 3.0.1.

Gerar e visualizar a especificação OpenAPI

É possível gerar e visualizar dinamicamente a especificação OpenAPI das integrações no editor de integração no Google Cloud console 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.
• Publique a integração. Para informações sobre como publicar uma integração, consulte Testar e publicar integrações.

Visualizar a especificação OpenAPI

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

Console

Para visualizar a especificação 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 Google Cloud projeto.

3. Clique na integração para a qual você quer visualizar 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 OpenAPI.

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

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

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

API

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

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

Dica:o curl geralmente vem pré-instalado para sistemas operacionais Linux e macOS. Se o curl não estiver instalado, faça o download na página de versões e downloads (em inglês) 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:generateOpenApiSpec"
          

Substitua:

• TRIGGER_NAME, TRIGGER_NAME_2, TRIGGER_NAME_n: os nomes do gatilho de API na integração para a qual você quer visualizar 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 doprojeto. Google Cloud
• LOCATION: o local do Google Cloud projeto.
  Observação:só é possível visualizar a especificação OpenAPI de várias integrações na mesma região.

Entender a especificação OpenAPI

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

Considerações

As considerações a seguir se aplicam ao visualizar a especificação OpenAPI da 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.
• O Application Integration atualmente 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.

A seguir

• Criar agentes de conversação com o Application Integration.
• Saiba mais sobre gatilhos de API.
• Saiba mais sobre como testar e publicar integrações.