[17.0.0.1 and later]

覆盖 Swagger 2.0 文档字段

使用 server.xml 文件中的 swaggerDefinition 属性,覆盖 /docs/explorer 端点提供的 Swagger 2.0 文档中一些字段。

开始之前

首先必须将 apiDiscovery-1.0 功能部件添加到 server.xml 文件,然后在 Liberty REST 端点中公开 Swagger 2.0 文档。完成在 Liberty 服务器上发现 REST API 文档中过程的步骤 1 和步骤 2。

过程

  1. 创建 swaggerDefinition 片段以指定包含要覆盖的字段的 JSON 或 YAML Swagger 片段。可以覆盖 infoschemesconsumesproducesexternalDocs 字段。

    例如,以下 swaggerDefinition 片段将更改 /explorer HTML 页面中的 descriptiontitle 和其他 info 字段。

    {  
      "swagger" : "2.0",
      "info":{  
         "description":"My description",
         "version":"1.0.0",
         "title":"My title",
         "x-ibm-css":"${server.config.dir}/css/acme-banner.css",
         "termsOfService":"http://swagger.io/terms/",
         "contact":{  
            "email":"apiteam@swagger.io"
         },
         "license":{  
            "name":"Apache 2.0",
            "url":"http://www.apache.org/licenses/LICENSE-2.0.html"
         }
      }
    }

    除了 titledescription 值,还可以在 /explorer HTML 页面中定制条幅和徽标 HTML 元素。 在 swaggerDefinition 片段的 info 字段中,可指定 x-ibm-css 字段以指向将覆盖条幅和徽标部分的 CSS 文件所在的位置。此 CSS 文件具有以下格式要求:

    • CSS 文件必须指定 .swagger-section #header CSS 元素。
    • 任何新徽标必须使用 images/custom-logo.png 格式,其中,custom-logo 是图像文件的名称。使徽标文件路径相对于 CSS 文件。
    • CSS 文件必须引用 background-image 属性设置为 url(images/custom-logo.png) 值的定制徽标图像。
    • 徽标文件必须为 PNG 格式。

    以下是覆盖 CSS 文件的示例:

    .swagger-section #header {
      background-image: url(images/custom-logo.png);
      background-repeat: no-repeat;
      background-color: lightslategray;
      background-position-x: 28px;
      padding-top: 20px;
      padding-right: 0px;
      padding-bottom: 20px;
      padding-left: 5px;
      height: 75px;
    }
  2. swaggerDefinition 属性添加到 server.xml 文件。

    swaggerDefinition 属性值可以是以下其中一个值:

    • .json.yaml 文件扩展名结束的本地文件的路径。此路径可以包含与运行时目录相关联的 Liberty 变量;例如:
      <apiDiscovery swaggerDefinition="${server.config.dir}/custom/swaggerDef.yaml" />
    • httphttps 开头的 Swagger 片段的绝对 URL;例如:
      <apiDiscovery swaggerDefinition="http://mycompany.com/api/swaggerDef.json" />
    • 在服务器上部署的应用程序的上下文根。上下文根以正斜杠 (/) 开头;例如:
      <apiDiscovery swaggerDefinition="/myApplication" />

    要提升包含一个已部署 Web 应用程序的 Liberty 服务器的用户体验,将 Web 应用程序的 Swagger 文档用作 swaggerDefinition 片段。 将在 /docs 端点提供的 Swagger 文档中覆盖来自应用程序的所有字段,即使未在 server.xml 中定义 swaggerDefinition 属性也是如此。在服务器上部署第二个 Web 应用程序时,所有受单个应用程序优化影响的字段还原为其缺省值。


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

文件名:twlp_api_discovery_swagger_def.html