Página do Gerenciador do Portal no Jitterbit API Manager

Introdução

A página Gerenciador do Portal permite gerar documentação OpenAPI para APIs personalizadas e proxy. A documentação resultante é exibida na página Portal, onde é possível interagir testando as APIs. Esta página descreve a interface do usuário da página Gerenciador do Portal dentro do API Manager.

Limitações

A página Gerenciador do Portal possui as seguintes limitações:

• A geração de documentação OpenAPI para serviços OData não é suportada.
• A geração de documentação OpenAPI para serviços de API que utilizam um método de solicitação personalizado não é suportada devido a uma limitação da especificação OpenAPI. APIs que incluem apenas serviços de API com método personalizado são exibidas apenas com um nome de tag de API.
• Apenas uma única página Portal para cada ambiente pode ser criada em uma organização Harmony.

Acessar a página do Gerenciador do Portal

Para acessar a página Gerenciador do Portal, use o menu do portal Harmony para selecionar API Manager > Gerenciador do Portal.

Cabeçalho da página do Gerenciador do Portal

A página Gerenciador do Portal também é chamada de Gerenciar Portal do Desenvolvedor, pois é a página onde você gerencia o que aparece na página Portal (também chamada de Gerenciar Portal do Desenvolvedor).

Essas opções aparecem na parte superior da página Gerenciador do Portal:

• Ambiente: Use o menu para selecionar o ambiente onde a documentação OpenAPI será gerada e, em seguida, exibida na página Portal da organização.

  Para atualizar a lista de ambientes, clique no ícone de atualização .

  Nota

  Apenas uma única página de Portal para cada ambiente pode ser criada em uma organização Harmony.

• Ver Documentação da API: Clique para ir para a página Portal, onde a documentação interativa da API gerada é exibida.

• Regenerar Documentos e Publicar: Clique para sobrescrever e publicar a documentação OpenAPI 2.0 na página Portal para todas as APIs personalizadas e proxy no ambiente selecionado. Serviços OData estão excluídos. Se você publicou uma nova API personalizada ou proxy e deseja regenerar automaticamente a documentação para incluir quaisquer novas APIs, deve usar esta opção.

  Aviso

  Usar esta opção sobrescreve a documentação da API existente, incluindo quaisquer personalizações. Antes de usar esta opção, é recomendável fazer uma cópia manual da documentação da API existente, copiando-a para um editor de texto externo. Após regenerar a documentação, reaplique manualmente quaisquer personalizações colando-as no editor de documentação da API conforme apropriado.

• Salvar e Publicar: Clique para salvar e publicar a documentação da API na página Portal. Se você aplicou quaisquer personalizações à documentação da API gerada automaticamente, deve usar esta opção para publicar a documentação na página Portal.

Personalizar a página do Portal

A página Gerenciador do Portal permite que você personalize a página Portal com uma imagem, como um logotipo da empresa, ou com edições na documentação da API gerada automaticamente:

• Navegar em Arquivos Locais: Clique para selecionar uma imagem que atenda aos requisitos listados:

  

  A imagem carregada é publicada automaticamente na página Portal sem precisar clicar em Regenerar Documentos e Publicar ou Salvar e Publicar.

Para remover uma imagem após o upload, clique em Remover Imagem:

• Organização: A organização Harmony que está sendo acessada atualmente.

• URL Base: A URL base para o serviço da API. Clique no ícone de copiar para copiar a URL base para sua área de transferência.

Editar a documentação da API

A documentação interativa seguindo a Especificação OpenAPI 2.0 é gerada automaticamente para todas as APIs personalizadas e proxy no ambiente selecionado.

As definições OpenAPI são exibidas no editor no lado esquerdo da página e são renderizadas como documentação interativa Swagger UI no lado direito da página.

É possível editar as definições OpenAPI diretamente dentro do editor no lado esquerdo da página. Estes são exemplos de personalizações para a documentação da API:

• Preencher metadados sobre a API, incluindo Campos Fixos como title, description, termsOfService, contact, license e version.

• Sobrescrever manualmente a documentação usando a Especificação OpenAPI 3.0.

Após fazer edições na documentação da API, clique em Salvar e Publicar para salvar e publicar a documentação na página Portal.

Para regenerar e publicar a documentação após publicar uma nova API, use o botão Regenerar Docs e Publicar.

Testar APIs

A documentação da API gerada a partir das definições OpenAPI mostradas no editor à esquerda da página é renderizada como documentação interativa Swagger UI no lado direito da página. Você pode usar o swagger interativo para testar os serviços da API:

• Esquemas: Use o menu suspenso para selecionar entre os esquemas disponíveis suportados pelas definições OpenAPI.

• Autorizar: Se alguma das APIs dentro do ambiente selecionado exigir uma autorização definida por um perfil de segurança atribuído, um botão Autorizar é exibido. Ao clicar, um diálogo exibe quaisquer autorizações disponíveis. Preencha os campos conforme necessário para testar as APIs com os métodos de autorização fornecidos.

  Ao clicar em Autorizar, um diálogo exibe quaisquer autorizações disponíveis. Preencha os campos conforme necessário para testar as APIs com os métodos de autorização fornecidos:

  

Serviços da API

Cada serviço da API é listado com seu método:

O ícone de autorização indica se o serviço da API requer autorização:

• : Nenhuma autorização é necessária.
• : Autorização é necessária.

Clique na linha do endpoint para visualizar informações sobre seus parâmetros e respostas – descritas abaixo.

Experimente

Em um serviço da API expandido, clique no botão Experimente para testar a API. Um pedido de API configurável é expandido:

• Cancelar: Clique para colapsar a solicitação de API configurável.

• Executar: Depois que os campos da solicitação forem configurados, clique para gerar o Curl e a URL da Solicitação a serem usados para testes:

  

  • Curl: A solicitação cURL para os valores inseridos nos campos da solicitação de API. Clique no ícone para copiar o cURL para sua área de transferência.

  • URL da Solicitação: A URL da solicitação para os valores inseridos nos campos da solicitação.

• Limpar: Clique para limpar os valores inseridos nos campos da solicitação de API.

Possíveis respostas da API – aquelas incluídas na documentação da API – são exibidas para cada serviço de API:

• Resposta do servidor: Exibe quaisquer respostas de servidor documentadas.

• Respostas: Exibe códigos de status HTTP documentados e suas descrições.