Página do Gerenciador de Portal no Jitterbit API Manager

Introdução

A página Gerenciador de Portal permite gerar documentação OpenAPI para todas as APIs personalizadas e proxy em um ambiente de uma só vez. A documentação resultante é exibida na página Portal da API, onde é possível interagir com ela testando as APIs. Para gerar documentação para uma API individual, use a aba Documentação na página APIs. Esta página descreve a interface do usuário da página Gerenciador de Portal dentro do API Manager.

Limitações

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

• A geração de documentação OpenAPI para APIs OData não é suportada ao usar Regenerar Docs. Para gerar documentação para uma API OData individual, use a aba Documentação na página APIs.
• 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 de método personalizado são exibidas apenas com um nome de tag de API.
• Apenas uma única página Portal da API para cada ambiente pode ser criada em uma organização Harmony.

Acessar a página do Gerenciador de Portal

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

Editor OpenAPI

O Editor OpenAPI inclui os seguintes controles:

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

  Nota

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

• Upload de logo: Você pode personalizar a página Portal API arrastando e soltando uma imagem na zona de upload ou selecionando uma manualmente. Seu upload é publicado automaticamente na página Portal API sem precisar clicar em Regenerar Docs ou Salvar e Publicar.

• Regenerar Docs: Clique para regenerar e publicar a documentação OpenAPI 2.0 na página Portal API para todas as APIs personalizadas e proxy no ambiente selecionado. APIs OData estão excluídas. 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.

  Quaisquer personalizações que você salvou anteriormente na documentação são preservadas e reaplicadas automaticamente sempre que possível. Se uma personalização entrar em conflito com a documentação regenerada, você deve resolver o conflito antes de poder salvar e publicar a documentação. Para mais informações, veja Resolver conflitos de personalização.

• Salvar e Publicar: Clique para salvar e publicar a documentação da API na página Portal API. Se você aplicou alguma personalização à documentação da API gerada automaticamente, deve usar esta opção para publicar a documentação na página Portal API. Este botão fica desativado até que quaisquer conflitos de personalização sejam resolvidos.

• Editor: Quando você adiciona definições OpenAPI no editor, elas são renderizadas como documentação interativa Swagger UI na Prévia do Portal. Você pode editar as definições OpenAPI diretamente dentro do editor. Estes são exemplos de personalizações para a documentação da API:

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

  • Sobrescreva 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 do Portal da API.

Resolve customization conflicts

Quando você clica em Regenerar Docs, qualquer personalização que você salvou anteriormente é comparada com a nova documentação OpenAPI gerada para aquele ambiente.

• Sem conflitos: Se cada personalização puder ser reaplicada sem conflito, elas são reaplicadas automaticamente, e uma mensagem de confirmação informa quantas personalizações foram reaplicadas.

• Conflitos: Se uma personalização entrar em conflito com a documentação regenerada, por exemplo, quando o valor subjacente de um campo personalizado mudou, uma mensagem Personalizações detectadas aparece junto com uma contagem de personalizações pendentes. Regenerar Docs e Salvar e Publicar ficam desabilitados até que cada conflito seja resolvido.

  

  Cada conflito é exibido diretamente no editor entre os marcadores <<<<<<< System generated e >>>>>>> Current customization, mostrando o conteúdo recém-gerado acima do divisor e sua personalização existente abaixo dele. Para cada conflito, faça uma das seguintes ações:

  • Aplicar personalização: Clique para manter sua personalização existente e descartar o conteúdo recém-gerado.

  • Ignorar personalização: Clique para descartar sua personalização existente e manter o conteúdo recém-gerado.

  • Edite o conteúdo diretamente no editor para combinar ou reescrever os valores conflitantes conforme necessário.

Para descartar todas as personalizações pendentes de uma vez e manter apenas o conteúdo recém-gerado, clique em Ignorar todas as personalizações.

Uma contagem em execução de personalizações Aplicadas, Ignoradas e Pendentes é exibida acima do editor enquanto existirem conflitos. Após cada conflito ser resolvido e Pendentes atingir 0, clique em Salvar e Publicar para publicar a documentação resolvida na página do Portal da API.

Pré-visualização do Portal

Você pode visualizar as definições da API como documentação interativa do Swagger UI na Pré-visualização do Portal.

• Organização: A organização Harmony atualmente acessada.

• Pesquisar: Insira um nome de API, nome de serviço ou método para filtrar as APIs Disponíveis que correspondem à consulta.

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

• APIs Disponíveis: Agrupa seus serviços de API pelo root do serviço, por exemplo, livro ou empréstimo. Clique nas setas para expandir ou colapsar as APIs nesse grupo. Use Expandir/Colapsar tudo para mostrar ou ocultar a lista de APIs.

Testar APIs

Quando você seleciona um endpoint de API, sua documentação interativa do Swagger UI aparece no lado direito da página. Você pode usar o Swagger interativo para testar os serviços da API.

• 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. Quando você clica em Autorizar, um diálogo exibe quaisquer autorizações disponíveis. Complete a entrada conforme necessário para testar APIs com os métodos de autorização fornecidos.

  

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

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

• Experimente: Clique para testar a API. Uma solicitação de API configurável é expandida:

  

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

  • Executar: Após configurar os campos da solicitação, clique neste botão 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 da 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 da API.

Cada serviço de API exibe possíveis respostas da API que estão incluídas na documentação da API:

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

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

Solução de Problemas

Para solução de problemas relacionada, consulte o seguinte no guia de solução de problemas do API Manager:

• Portal da API não refletindo alterações no projeto

• Excluir uma API não atualiza a documentação do Portal da API