Customizando a interface com o usuário do OpenAPI

É possível customizar aspectos da interface com o usuário do OpenAPI disponíveis nos terminais /openapi/ui e /api/explorer. O Liberty monitora mudanças nos arquivos CSS de customização para processar e atualizar mudanças na IU do OpenAPI .

Antes de Começar

Para saber como construir e ativar a documentação do OpenAPI , consulte Gerando a documentação da API REST com MicroProfile OpenAPI.

Procedimento

  1. Customize o arquivo CSS para editar o estilo dos elementos HTML na barra de cabeçalho da IU do OpenAPI.
    Este arquivo CSS possui os requisitos de formato a seguir para que ele seja considerado válido.
    • O arquivo CSS especifica pelo menos um elemento que inicia com .swagger-ui .headerbar.
    • Apenas os conteúdos que são especificados sob elementos CSS que começam com o .swagger-ui .headerbar são usados.
    • O arquivo de logotipo customizado que é referenciado pelo arquivo CSS deve estar no formato PNG.
    • Um arquivo de logotipo customizado deve ser nomeado custom-logo.png e colocado em images/custom-logo.png.
    • O caminho do arquivo de logotipo deve ser relativo ao arquivo CSS.
    • O arquivo CSS deve referenciar a imagem do logotipo com a propriedade background-image configurada para o valor url(images/custom-logo.png).

    O fragmento a seguir ilustra como substituir um arquivo CSS:

    .swagger-ui .headerbar {
   background-color: #5f3345;
}
 .swagger-ui .headerbar .headerbar-wrapper {
   background-image: url(images/custom-logo.png);
}
  2. Configure o monitoramento de arquivo para seu arquivo CSS de customização.

    É possível salvar seu arquivo CSS customizado nos locais $server.config.dir/mpopenapi/customization.css e $server.config.dir/openapi-3.1/customization.css para monitoramento automático. O local do primeiro arquivo CSS se aplica ao terminal do /openapi/ui.  O local do segundo arquivo CSS se aplica ao terminal do /api/explorer. Se você também deseja especificar um logotipo customizado, salve-o nos locais $server.config.dir/mpopenapi/images/custom-logo.png e $server.config.dir/openapi-3.1/images/custom-logo.png e referencie-o dentro do arquivo CSS em ambos os locais.

    Nota: Somente os arquivos CSS são monitorados para atualizações. Os arquivos de logotipo não são monitorados. Uma mudança em um dos arquivos de logotipo deve ser seguida por uma atualização em seu arquivo CSS correspondente para que ela seja selecionada dinamicamente.
  3. Opcional: Monitoramento do arquivo de controle para arquivos de customização.

    Liberty monitora continuamente os arquivos de customização do CSS por padrão. No entanto, o monitoramento dos arquivos usa recursos adicionais do sistema. É possível mudar a frequência com que os arquivos monitorados são verificados quanto a atualizações. Se você não tiver nenhum arquivo de customização, então é benéfico desligar o monitoramento de arquivos.

    A propriedade de configuração mp.openapi.extensions.liberty.file.polling.interval especifica com que frequência os arquivos monitorados são verificados quanto a atualizações. O valor dessa propriedade é um número inteiro não negativo. A unidade para o intervalo é segundos. O valor padrão é 2 segundos. Configurar o valor para 0 desativa o monitoramento do arquivo.
    A configuração é injetada pela especificação do MicroProfile Config.
    Nota: O valor desta propriedade só é verificado quando os recursos mpOpenAPI-1.0 ou openapi-3.1 estão habilitados.