Personalización de la interfaz de usuario OpenAPI

Puede personalizar aspectos del la interfaz de usuario OpenAPI disponibles en los puntos finales /openapi/ui y /api/explorer. Liberty supervisa los cambios en los archivos CSS de personalización para procesar y actualizar los cambios en la interfaz de usuario de OpenAPI .

Antes de comenzar

Para aprender a crear y habilitar la documentación de OpenAPI , consulte Generación de documentación de API REST con MicroProfile OpenAPI.

Procedimiento

  1. Personalice el archivo CSS para editar el estilo de los elementos HTML en la barra de cabecera de la IU de OpenAPI.
    Este archivo CSS tiene los requisitos de formato siguientes que se deben considerar válidos.
    • El archivo CSS especifica, al menos, un elemento que empieza con .swagger-ui .headerbar.
    • Solo se utilizan los contenidos que se especifican bajo elementos CSS que empiezan con .swagger-ui .headerbar.
    • El archivo de logotipo personalizado referenciado por el archivo CSS debe estar en formato PNG.
    • Un archivo de logotipo personalizado debe denominarse custom-logo.png y debe colocarse en images/custom-logo.png.
    • La vía de acceso del archivo de logotipo debe ser relativa al archivo CSS.
    • El archivo CSS debe hacer referencia a la imagen de logotipo con la propiedad background-image establecida en el valor url(images/custom-logo.png).

    El fragmento de código siguiente ilustra cómo alterar temporalmente un archivo CSS:

    .swagger-ui .headerbar {
   background-color: #5f3345;
}
 .swagger-ui .headerbar .headerbar-wrapper {
   background-image: url(images/custom-logo.png);
}
  2. Configure la supervisión de archivos para el archivo CSS de personalización.

    Puede guardar el archivo CSS personalizado en las ubicaciones $server.config.dir/mpopenapi/customization.css y $server.config.dir/openapi-3.1/customization.css para la supervisión automática. La ubicación del primer archivo CSS se aplica al punto final /openapi/ui. La ubicación del segundo archivo CSS se aplica al punto final /api/explorer. Si también desea especificar un logotipo personalizado, guárdelo en las ubicaciones $server.config.dir/mpopenapi/images/custom-logo.png y $server.config.dir/openapi-3.1/images/custom-logo.png y haga referencia a él en el archivo CSS en las dos ubicaciones.

    Nota: Sólo se supervisan las actualizaciones de los archivos CSS. Los archivos de logotipo no se supervisan. Un cambio en uno de los archivos de logotipo debe ir seguido de una actualización en su correspondiente archivo CSS para que se seleccione dinámicamente.
  3. Opcional: Supervisión de archivos de control para archivos de personalización.

    Liberty supervisa continuamente los archivos de personalización CSS de forma predeterminada. Sin embargo, la supervisión de los archivos utiliza recursos de sistema adicionales. Puede modificar la frecuencia con la que se comprueban las actualizaciones en los archivos supervisados. Si no tiene ningún archivo de personalización, es beneficioso desactivar la supervisión de archivos.

    La propiedad de configuración mp.openapi.extensions.liberty.file.polling.interval especifica con qué frecuencia se comprueban las actualizaciones en los archivos supervisados. El valor de esta propiedad es un entero no negativo. La unidad para el intervalo son los segundos. El valor predeterminado es 2 segundos. Al establecer el valor en 0, se inhabilita la supervisión de archivos.
    La especificación de MicroProfile Config inyecta la configuración.
    Nota: El valor de esta propiedad sólo se comprueba cuando las características mpOpenAPI-1.0 o openapi-3.1 están habilitadas.