![[17.0.0.1 and later]](../ng_v17001plus.gif)
覆盖 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。
过程
- 创建 swaggerDefinition 片段以指定包含要覆盖的字段的 JSON 或 YAML Swagger 片段。可以覆盖 info、schemes、consumes、produces 和 externalDocs 字段。
例如,以下 swaggerDefinition 片段将更改 /explorer HTML 页面中的 description、title 和其他 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" } } }
除了 title 和 description 值,还可以在 /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; }
- 将 swaggerDefinition 属性添加到 server.xml 文件。
swaggerDefinition 属性值可以是以下其中一个值:
- 以 .json 或 .yaml 文件扩展名结束的本地文件的路径。此路径可以包含与运行时目录相关联的 Liberty 变量;例如:
<apiDiscovery swaggerDefinition="${server.config.dir}/custom/swaggerDef.yaml" />
- 以 http 或 https 开头的 Swagger 片段的绝对 URL;例如:
<apiDiscovery swaggerDefinition="http://mycompany.com/api/swaggerDef.json" />
- 在服务器上部署的应用程序的上下文根。上下文根以正斜杠 (/) 开头;例如:
<apiDiscovery swaggerDefinition="/myApplication" />
要提升包含一个已部署 Web 应用程序的 Liberty 服务器的用户体验,将 Web 应用程序的 Swagger 文档用作 swaggerDefinition 片段。 将在 /docs 端点提供的 Swagger 文档中覆盖来自应用程序的所有字段,即使未在 server.xml 中定义 swaggerDefinition 属性也是如此。在服务器上部署第二个 Web 应用程序时,所有受单个应用程序优化影响的字段还原为其缺省值。
- 以 .json 或 .yaml 文件扩展名结束的本地文件的路径。此路径可以包含与运行时目录相关联的 Liberty 变量;例如:

文件名:twlp_api_discovery_swagger_def.html