![[17.0.0.1 以及更新版本]](../ng_v17001plus.gif)
改寫 Swagger 2.0 文件欄位
在 server.xml 檔中使用 swaggerDefinition 屬性,以改寫 Swagger 2.0 文件(由 /docs 和 /explorer 端點提供)中的部分欄位。
開始之前
您必須先將 apiDiscovery-1.0 特性新增至 server.xml 檔,然後在 Liberty REST 端點中公開 Swagger 2.0 說明文件。 完成探索 Liberty 伺服器中的 REST API 說明文件中的程序步驟 1 和 2。
程序
- 建立 swaggerDefinition Snippet 來指定 JSON 或 YAML Swagger Snippet,其中包含要改寫的欄位。您可以改寫 info、schemes、consumes、produces 及 externalDocs 欄位。
例如,下列 swaggerDefinition Snippet 會在 /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 Snippet 的 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" />
- Swagger Snippet 的絕對 URL,開頭為 http 或 https;例如:
<apiDiscovery swaggerDefinition="http://mycompany.com/api/swaggerDef.json" />
- 部署在伺服器上之應用程式的環境定義根目錄。環境定義根目錄的開頭為正斜線 (/);例如:
<apiDiscovery swaggerDefinition="/myApplication" />
為了加強 Liberty 伺服器(包含一個已部署的 Web 應用程式)的使用者體驗,Web 應用程式的 Swagger 文件會作為 swaggerDefinition Snippet。 即使 server.xml 中未定義 swaggerDefinition 屬性,/docs 端點所提供的 Swagger 文件中也會置換應用程式的所有欄位。 當伺服器上部署第二個 Web 應用程式時,受到單一應用程式最佳化所影響的所有欄位會回復為預設值。
- 本端檔案的路徑,結尾是 .json 或 .yaml 副檔名。這個路徑可以包含與執行時期目錄相關聯的 Liberty 變數;例如:

檔名:twlp_api_discovery_swagger_def.html