![[17.0.0.3 and later]](../ng_v17003plus.gif)
定制 OpenAPI 文档
您可以使用 externalDocs 和 info 之类的元素来定制 /api/docs 端点处提供的主要 OpenAPI 文档以及 /api/explorer 处提供的 OpenAPI 用户界面的各个方面。Liberty 将监视对缺省路径位置处的定制文件所作的更改,以处理并更新对主要 OpenAPI 文档和 UI 的更改。
开始之前
要了解如何构建和启用 OpenAPI 文档,请参阅使用 OpenAPI 生成 REST API 文档。
使用样本 OpenAPI V3 airlines 应用程序生成文档并呈现可定制 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) 值来引用徽标图像。
.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。- 将 YAML、YML 或 JSON 文件类型的定制片段保存在 ${server.config.dir}/openapi/customization.file_type 中,以使用缺省定制文件监视。
- 可选: 在 Liberty 服务器配置文件中,添加其 customization 属性引用该片段的 openapi 元素。
显式设置 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 设置为 true。当 disableFileMonitor 属性设置为 true 时,也不会监视缺省定制定义位置。<openapi disableFileMonitor="true" />

文件名:twlp_api_openapi_custom.html