Gerenciador de Portais¶

Introdução¶

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

Limitações¶

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

• Geração de documentação OpenAPI para OData Services não é suportado.
• Geração de documentação OpenAPI para serviços API usando um método de solicitação personalizado não é compatível 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.

Acessando a Página do Gerenciador do Portal¶

A página Portal Manager pode ser acessada no menu Harmony Portal ou em outras páginas do API Manager:

• Da Casa ou Downloads ou nas páginas Cloud Studio, Vinyl, Marketplace, Management Console, EDI, ou Citizen Integrator, use o menu Harmony Portal no canto superior esquerdo para ir para API Manager > Portal Manager:

  

• Em Minhas APIs, Registros de API, Análise, Perfis de segurança, Grupos de IPs Confiáveis ou Grupos de API, use o menu de navegação do API Manager para selecionar Portal Manager:

  

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 no Portal (também chamada de Gerenciar portal do desenvolvedor).

Estas opções aparecem na parte superior da página 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 de API, Análise e Perfis de segurança.

• Ambiente: Use o menu para selecionar o ambiente onde a documentação do 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

  Apenas 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 da API interativa gerada é renderizada.

• Regerar 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 de proxy no ambiente selecionado. Os serviços OData estão excluídos. Se você publicou uma nova proxy de API e deseja regenerar automaticamente a documentação para incluir quaisquer novas APIs, deverá 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, é recomendado 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 do Portal. Se você aplicou alguma customização à documentação da API gerada automaticamente, deverá usar esta opção para publicar a documentação na página Portal.

Personalize a Página do Portal¶

O portal pode ser personalizada com uma imagem, como o logotipo de uma empresa, ou com edições na documentação da API gerada automaticamente.

Adicionar uma Imagem¶

Para adicionar uma imagem, clique em Procurar arquivos locais e selecione uma imagem que atenda aos requisitos listados:

A imagem carregada é publicada automaticamente na página do Portal sem a necessidade de clicar em Regerar documentos e publicar ou Salvar e publicar.

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

Edite a Documentação da API¶

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

As definições OpenAPI são mostradas no editor no lado esquerdo da página e são renderizadas como interativa 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 customizações para a documentação da API:

• Preencher metadados sobre a API, incluindo Campos Fixos como title, description, termsOfService, contact, license, e version.
• Substitua 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 no Portal página.

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

Testar APIs¶

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, conforme mostrado acima. A documentação da API renderizada também é exibida no Portal página. Você pode usar a documentação interativa para testar chamadas de proxy de API para validar se estão funcionando corretamente.

A documentação dos elementos comuns da UI do Swagger é fornecida abaixo. Para documentação sobre todos os elementos possíveis, consulte Especificação OpenAPI 2.0 ou Especificação OpenAPI 3.0.

Esquemas¶

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

Autorização¶

Se alguma das APIs no ambiente selecionado exigir uma autorização definida por um perfil de segurança, um botão Autorizar será exibido:

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

Endpoints¶

Cada endpoint da API é listado com seu método:

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

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

Clique na linha do endpoint para expandir as informações sobre seus parâmetros e respostas:

Experimente¶

Clique no botão Experimente para expandir uma área configurável:

Configure a solicitação a ser enviada ao endpoint e clique em Executar:

A solicitação enviada é enviada ao endpoint e a resposta é retornada: