[17.0.0.3 and later]

定制 OpenAPI 文档

您可以使用 externalDocsinfo 之类的元素来定制 /api/docs 端点处提供的主要 OpenAPI 文档以及 /api/explorer 处提供的 OpenAPI 用户界面的各个方面。Liberty 将监视对缺省路径位置处的定制文件所作的更改,以处理并更新对主要 OpenAPI 文档和 UI 的更改。

开始之前

要了解如何构建和启用 OpenAPI 文档,请参阅使用 OpenAPI 生成 REST API 文档

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

过程

  1. 在 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;
    }
  2. 配置对定制文件的文件监视。

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

    注: 仅监视定制文件以了解是否存在更新。将不监视 CSS 和徽标文件。也不监视 URL。
    1. 将 YAML、YML 或 JSON 文件类型的定制片段保存在 ${server.config.dir}/openapi/customization.file_type 中,以使用缺省定制文件监视。
    2. 可选: 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" />
  3. 可选: 禁用对定制文件的文件监视。

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

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

用于指示主题类型的图标 任务主题

文件名:twlp_api_openapi_custom.html