Customizing OpenAPI user interface

You can customize aspects of the OpenAPI user interface available at the /openapi/ui and/api/explorer endpoints. Liberty monitors changes to the customization CSS files to process and update changes to the OpenAPI UI.

1. Customize the CSS file to edit the style of the HTML elements in the header bar of the OpenAPI UI.
   This CSS file has the following format requirements to be considered valid.

   • The CSS file specifies at least one element that starts with .swagger-ui .headerbar.
   • Only the contents that are specified under CSS elements that start with the .swagger-ui .headerbar are used.
   • The custom logo file that is referenced by the CSS file must be in PNG format.
   • A custom logo file must be named custom-logo.png and placed at images/custom-logo.png.
   • The logo file path must be relative to the CSS file.
   • The CSS file must reference the logo image with the background-image property set to url(images/custom-logo.png) value.

   The following snippet illustrates how to override a CSS file:

   .swagger-ui .headerbar {
      background-color: #5f3345;
   }
    .swagger-ui .headerbar .headerbar-wrapper {
      background-image: url(images/custom-logo.png);
   }
   

2. Configure file monitoring for your customization CSS file.

   You can save your custom CSS file in the $server.config.dir/mpopenapi/customization.css and $server.config.dir/openapi-3.1/customization.css locations for automatic monitoring. The location of the first CSS file applies to the /openapi/ui endpoint.  The location of the second CSS file applies to the /api/explorer endpoint. If you also want to specify a custom logo, save it in the $server.config.dir/mpopenapi/images/custom-logo.png and $server.config.dir/openapi-3.1/images/custom-logo.png locations and reference it within the CSS file at both locations.

   Note: Only the CSS files are monitored for updates. The logo files are not monitored. A change to one of the logo files must be followed by an update to its corresponding CSS file for it to be picked up dynamically.
3. Optional: Control file monitoring for customization files.

   Liberty continuously monitors the CSS customization files by default. However, monitoring the files uses additional system resources. You can alter the frequency that monitored files are checked for updates. If you do not have any customization file, then it is beneficial to turn off file monitoring.

   The configuration property mp.openapi.extensions.liberty.file.polling.interval specifies how frequently monitored files are checked for updates. The value of this property is a non-negative integer. The unit for the interval is seconds. The default value is 2 seconds. Setting the value to 0 disables file monitoring.

   Configuration is injected by the MicroProfile Config specification.

   Note: The value of this property is only checked when the mpOpenAPI-1.0 or openapi-3.1 features are enabled.