Customizing OpenAPI documentation

You can customize aspects of the main OpenAPI document available at the /api/docs endpoint and the OpenAPI User Interface at /api/explorer with elements such as the externalDocs element and the info element. Liberty monitors changes to the customization files at the default path locations to process and update changes to the main OpenAPI document and UI.

Stabilized features: The OpenAPI V3 features, openapi-3.0 and openapi-3.1, are stabilized. You can continue to use the features. However, the strategic alternative is to use a MicroProfile OpenAPI feature such as mpOpenAPI-3.0.

Before you begin

To learn how to build and enable OpenAPI documentation, see Generating REST API documentation with OpenAPI.

Generate documentation and render an example of the customizable UI using the Sample OpenAPI V3 airlines application.

Procedure

Define a customization in an OpenAPI snippet.
Create a snippet that follows the structure of the OpenAPI 3.0.0 specification. The snippet can be in a YAML or JSON file or available at a URL.
The info element provides title, description, and other information. You can customize the title and description values. You also can customize the header bar to edit the logo, the filter box, and the filter button. Inside the info field of the customization snippet, use an x-ibm-css field to point to the location of a CSS file that styles the HTML elements in the header bar.
The snippet does not need to be complete on its own. The following example snippet customizes the info element, which points to a CSS that styles the header bar of the OpenAPI UI.
```
---
openapi: 3.0.0
info:
  title: Airlines APIs
  description: Book flights and manage reservations
  version: 2.1.0
  x-ibm-css: ${server.config.dir}/openapi/header.css
```
The CSS can be a local file or available at a URL. The path can include Liberty variables that are associated with runtime directories.
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 example snippet shows an overriding CSS file.
```
.swagger-ui .headerbar {
   background-color: #5f3345;
}
 .swagger-ui .headerbar .headerbar-wrapper {
   background-image: url(images/custom-logo.png);
}
 .swagger-ui .headerbar .filter-wrapper .filter-button {
    background: rgba(252, 48, 81, 0.53);
   color: #e8e8e8;
}
 .swagger-ui .headerbar .filter-wrapper input[type=text] {
        border: 1px solid #ebebeb;
}
```
Configure file monitoring for your customization files.

You can save your customization file in the default location for automatic monitoring or you can change the server configuration to define a location for your file. If more than one default customization file is specified, you see a warning message output to the console that indicates the customization file that is monitored and the files that are ignored. The customization file that is selected for monitoring is monitored continuously by Liberty until it is deleted.

Note: Only customization files are monitored for updates. The CSS and logo files are not monitored. URLs are not monitored.
1. Save the customization snippet in either YAML, YML, or JSON file type at ${server.config.dir}/openapi/customization.file_type to use the default customization file monitoring.
2. Optional: Add an openapi element with a customization attribute that references the snippet in the Liberty server configuration file.
  
  Default customization definition locations are not monitored when the customization attribute is set explicitly. The customization attribute can specify a YAML, YML, or JSON file, which is monitored by Liberty. The path can include Liberty variables that are associated with runtime directories, like in the following example.
```
<openapi customization="${server.config.dir}/custom/customInfo.yaml" />
```
  The customization attribute can also specify a URL that returns an OpenAPI snippet.
```
<openapi customization="http://myWebsite.com/myCustomOpenAPI" />
```
Optional: Disable file monitoring for customization files.

Liberty continuously monitors the customization files by default. However, monitoring the files uses extra system resources. If you do not have any customization files or if your customization files are static and do not change, then it is beneficial to turn off file monitoring.

In your server configuration file, set the disableFileMonitor Boolean attribute to true for the openapi element. Default customization definition locations are also not monitored when the disableFileMonitor attribute is set to true.
```
<openapi disableFileMonitor="true" />
```