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

A Application Integration permite 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 sua integração, você pode:

  • Entenda de forma abrangente os endpoints de API, os métodos e as estruturas de dados da sua integração.
  • Ofereça uma visão detalhada e centralizada da API da sua integração para tornar o desenvolvimento e a solução de problemas mais eficientes.
  • Exponha suas APIs de integração e faça a integração com agentes de conversação. Consulte Criar agentes de conversação com a Application Integration.

O que é a especificação do OpenAPI?

Logotipo da especificação OpenAPI

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

Gerar e visualizar a especificação OpenAPI

É possível gerar e visualizar 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 gatilhos de API. Para informações sobre como configurar gatilhos de API, consulte Gatilhos de API.
  • Publique a integração. Para saber como publicar uma integração, consulte Testar e publicar integrações.

Ver especificação OpenAPI

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

Console

Para ver 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 é exibida, listando todas as integrações disponíveis no projeto do Google Cloud .

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

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

    • Para ver a especificação OpenAPI de um gatilho de API específico, selecione o gatilho na lista suspensa APIs.
    • Para baixar a especificação OpenAPI como um arquivo YAML, clique em download .

API

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

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

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 que você quer ver 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: ID do seu projeto do Google Cloud .
  • LOCATION: o local do projeto do Google Cloud .

Noções básicas sobre a especificação OpenAPI

A Application Integration gera a especificação OpenAPI para as 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 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.

components O campo schemas contém o esquema JSON para as variáveis de entrada e saída do gatilho da API.

O campo securitySchemes contém as informações de autenticação dos gatilhos da API.

Considerações

As seguintes considerações 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 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.
  • No momento, o Application Integration é compatível apenas com o 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 da OpenAPI usando o Editor do Swagger, talvez você encontre erros semânticos relacionados aos caminhos da API, como na imagem a seguir:

    Swagger Editor Swagger Editor

    Esses erros podem ser ignorados com segurança. A especificação OpenAPI ainda é válida.

A seguir