[18.0.0.1 and later]

定制 OpenAPI 用户界面

您可以定制 /openapi/ui 端点处提供的 OpenAPI 用户界面的各个方面。Liberty 监视对定制 CSS 文件所做的更改,以处理并更新对 OpenAPI UI 的更改。

开始之前

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

过程

  1. 定制 CSS 文件,以编辑 OpenAPI UI 的标题栏中 HTML 元素的样式。 此 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);
    }
  2. 配置对定制 CSS 文件的文件监视。

    您可以将定制 CSS 文件保存在 $server.config.dir/mpopenapi/customization.css 位置以进行自动监视。如果您还想要指定定制徽标,请将徽标保存在 $server.config.dir/mpopenapi/images/custom-logo.png 位置,并在 CSS 文件中对其进行引用。

    注: 仅监视 CSS 文件以了解是否存在更新。将不监视徽标文件。对徽标文件进行更改后,必须更新 CSS 文件,以便动态地应用更改。
  3. 可选: 控制对定制文件的文件监视。

    缺省情况下,Liberty 持续地监视 CSS 定制文件。然而,监视该文件会使用额外的系统资源。您可以变更检查受监视文件中是否存在更新的频率。如果您没有任何定制文件,那么关闭文件监视将会有益。

    配置属性 mp.openapi.extensions.liberty.file.polling.interval 用于指定检查受监视文件中是否存在更新的频率。此属性的值是一个非负整数。时间间隔单位为秒。缺省值为 2 秒。如果将值设置为 0,那么将禁用文件监视。
    配置由 MicroProfile Config 规范注入。
    注: 仅当 mpOpenAPI-1.0 功能部件处于启用状态时,才检查此属性的值。

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

文件名:twlp_api_mpopenapi_custom.html