定制 OpenAPI 文档

您可以使用诸如 externalDocs 元素和 info 元素之类的元素来定制在 /api/docs 端点和 OpenAPI 用户界面 /api/explorer 上提供的主要 OpenAPI 文档的各个方面。 Liberty 监视对缺省路径位置的定制文件的更改，以处理和更新对主 OpenAPI 文档和 UI 的更改。

已稳定的功能部件: OpenAPI V3 功能部件 openapi-3.0 和 openapi-3.1已稳定。您可继续使用这些功能部件。但是，战略替代方法是使用 MicroProfile OpenAPI 功能部件，例如 mpOpenAPI-3.0。

准备工作

要了解如何构建和启用 OpenAPI 文档，请参阅使用 OpenAPI。

使用样本 OpenAPI V3 航空公司应用程序生成文档并呈现可定制 UI 的示例。

过程

在 OpenAPI 片段中定义定制。
创建一个遵循 OpenAPI 3.0.0 规范的结构的片段。该片段可位于 YAML 或 JSON 文件中，也可以在 URL 处提供。
info 元素提供标题、描述和其他信息。您可以定制标题和描述值。还可以定制标题栏，以编辑徽标、过滤器框和过滤器按钮。在定制片段的 info 字段内，可使用 x-ibm-css 字段指向用于设置标题栏中的 HTML 元素样式的 CSS 文件所在的位置。
该片段就其本身而言无需完整。以下示例片段对 info 元素进行定制，该元素指向用于设置 OpenAPI UI 标题栏的样式的 CSS。
```
---
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
```
此 CSS 可以是一个本地文件，也可以在 URL 处提供。该路径可以包含与运行时目录相关联的 Liberty 变量。
此 CSS 文件必须满足以下格式要求才被视为有效：
- CSS 文件至少指定一个以 .swagger-ui .headerbar开头的元素。
- 仅使用在以 .swagger-ui .headerbar 开头的 CSS 元素下指定的内容。
- CSS 文件所引用的定制徽标文件必须为 PNG 格式。
- 定制徽标文件必须命名为 custom-logo.png，并放置在 images/custom-logo.png 中。
- 徽标文件路径必须相对于 CSS 文件。
- CSS 文件必须通过将 background-image 属性设置为 url(images/custom-logo.png) 值来引用徽标图像。
以下示例片段显示一个覆盖 CSS 文件。
```
.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;
}
```
配置对定制文件的文件监视。

您可以将定制文件保存在缺省位置以进行自动监视，也可以更改服务器配置以定义该文件的位置。如果指定了多个缺省定制文件，您会看到一条输出到控制台的警告消息，它指出所监视的定制文件以及所忽略的文件。选择要监视的定制文件由 Liberty 持续监视，直到将其删除为止。

注: 仅监视定制文件以获取更新。将不监视 CSS 和徽标文件。也不监视 URL。
1. 将定制片段保存在位于 ${server.config.dir}/openapi/customization.file_type 的 YAML ， YML 或 JSON 文件类型中，以使用缺省定制文件监视。
2. 可选: 添加具有 customization 属性的 openapi 元素，该属性引用 Liberty 服务器配置文件中的片段。
  
  显式设置 customization 属性后，将不监视缺省定制定义位置。 customization 属性可以指定受 Liberty监视的 YAML ， YML 或 JSON 文件。路径可以包含与运行时目录关联的 Liberty 变量，如以下示例中所示。
```
<openapi customization="${server.config.dir}/custom/customInfo.yaml" />
```
  customization 属性还可以指定返回 OpenAPI 片段的 URL。
```
<openapi customization="http://myWebsite.com/myCustomOpenAPI" />
```
可选: 对定制文件禁用文件监视。

缺省情况下， Liberty 持续监视定制文件。然而，监视这些文件会使用额外的系统资源。如果您没有任何定制文件，或者如果您的定制文件是静态文件且不会更改，那么关闭文件监视将会有益。

在服务器配置文件中，将 openapi 元素的 disableFileMonitor Boolean 属性设置为 true 。当 disableFileMonitor 属性设置为 true 时，也不会监视缺省定制定义位置。
```
<openapi disableFileMonitor="true" />
```