Gerenciador de Portal¶

Introdução¶

A página Portal Manager permite que você gere documentação OpenAPI para APIs personalizadas e proxy. A documentação resultante é exibida no Portal, onde você pode interagir com ela testando APIs. Esta página descreve a interface do usuário da página Portal Manager dentro do API Manager.

Limitações¶

A página Gerenciador do Portal tem estas limitações:

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

Acesse a Página do Gerenciador do Portal¶

A página Gerenciador do Portal pode ser acessada pelo menu do portal Harmony ou pelo menu de navegação do API Manager:

• Use o menu do portal Harmony para selecionar API Manager > Portal Manager:

  

• Ao acessar uma página do API Manager, use seu menu de navegação para selecionar Portal Manager:

  

Cabeçalho da Página do Portal Manager¶

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

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

• Navegação: Use o menu de navegação do API Manager para navegar entre as páginas do API Manager, incluindo Minhas APIs, Portal, Registros da API, Análise e Perfis de Segurança.

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

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

  Nota

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

• Ver documentação da API: Clique para ir para o Portal, onde a documentação interativa da API gerada é renderizada.

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

  Aviso

  Usar esta opção substitui 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 alguma personalização à documentação da API gerada automaticamente, você deve usar esta opção para publicar a documentação na página Portal.

Personalize a Página do Portal¶

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

• Navegar pelos arquivos locais: Clique para selecionar uma imagem que atenda aos requisitos listados:

  

  A imagem carregada é publicada automaticamente na página do 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 está sendo acessada no momento.

• URL base: A URL base para o serviço de API. Clique em ícone de cópia para copiar o URL base para sua área de transferência.

Editar a Documentação da API¶

Documentação interativa seguindo a OpenAPI Specification 2.0 é gerado automaticamente para todas as APIs personalizadas e proxy no ambiente selecionado.

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

Você pode editar as definições OpenAPI diretamente no editor no lado esquerdo da página. Estes são exemplos de personalizações para a documentação da API:

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

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

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

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

APIs de Teste¶

A documentação da API gerada a partir das definições OpenAPI mostradas no editor no lado esquerdo da página é renderizada como interativa Swagger UI documentação 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 do OpenAPI.

• Autorizar: Se alguma das APIs no ambiente selecionado exigir uma autorização definida por um perfil de segurança atribuído, um botão Autorizar é exibido. Após clicar, uma caixa de diálogo exibe todas as autorizações disponíveis. Complete a entrada conforme necessário para testar APIs com os métodos de autorização fornecidos.

  Ao clicar em Autorizar, uma caixa de diálogo exibe todas as autorizações disponíveis. Complete a entrada conforme necessário para testar APIs com os métodos de autorização fornecidos:

  

Serviços de API¶

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

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

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

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

Experimente¶

Em um serviço de API expandido, clique no botão Try it out para testar a API. Uma solicitação de API configurável é expandida:

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

• Executar: Depois que todos os campos de solicitação estiverem configurados, clique para gerar o Curl e o URL de solicitação a serem usados para testes:

  

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

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

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

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

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

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