![[18.0.0.1 and later]](../ng_v18001plus.gif)
Customizing OpenAPI user interface
You can customize aspects of the OpenAPI user interface available at the /openapi/ui endpoint. Liberty monitors changes to the customization CSS file to process and update changes to the OpenAPI UI.
Before you begin
To learn how to build and enable OpenAPI documentation, see Generating REST API documentation with MicroProfile OpenAPI 1.0.
Procedure
- 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); }
- Configure file monitoring for your customization CSS file.
You can save your custom CSS file in the $server.config.dir/mpopenapi/customization.css location for automatic monitoring. If you also want to specify a custom logo, save it in the $server.config.dir/mpopenapi/images/custom-logo.png location and reference it within the CSS file.
Note: Only the CSS file is monitored for updates. The logo file is not monitored. A change to the logo file must be followed by an update to the CSS file for it to be picked up dynamically. - Optional: Control file monitoring for customization files.
Liberty continuously monitors the CSS customization file by default. However, monitoring the file 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 feature is enabled.

File name: twlp_api_mpopenapi_custom.html