![[17.0.0.3 以及更新版本]](../ng_v17003plus.gif)
自訂 OpenAPI 說明文件
您可以針對位於 /api/docs 端點的主要 OpenAPI 文件以及位於 /api/explorer 的 OpenAPI 使用者介面,使用 externalDocs 和 info 等元素,來自訂其各個層面。Liberty 會監視位於預設路徑位置之自訂作業檔案的變更,來處理及更新主要 OpenAPI 文件和使用者介面的變更。
開始之前
如果要瞭解如何建置和啟用 OpenAPI 說明文件,請參閱使用 OpenAPI 來產生 REST API 說明文件。
使用範例 OpenAPI 第 3 版 airlines 應用程式,來產生說明文件,並呈現可自訂的使用者介面範例。
程序
- 在 OpenAPI Snippet 中定義一項自訂作業。 建立一個遵循 OpenAPI 3.0.0 規格結構的 Snippet。此 Snippet 可以放在
YAML 或 JSON 檔案中,或從 URL 取得。
info 元素提供標題、說明和其他資訊。您可以自訂標題和說明的值。您也可以自訂標頭列,以編輯標誌、過濾框和過濾按鈕。在自訂作業 Snippet 的 info 欄位內,針對設定了標頭列 HTML 元素樣式的 CSS 檔案,使用 x-ibm-css 欄位來指向該 CSS 檔的位置。
Snippet 不需要獨立完成。下列的範例 Snippet 會自訂 info 元素,使其指向設定了 OpenAPI 使用者介面之標頭列樣式的 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 開頭的元素。
- 只會使用 CSS 元素之下所指定以 .swagger-ui .headerbar 開頭的內容。
- CSS 檔案所參照之自訂標誌檔案必須是 PNG 格式。
- 自訂標誌檔案必須命名為 custom-logo.png,並且放在 images/custom-logo.png 中。
- 標誌檔案路徑必須相對於 CSS 檔案。
- CSS 檔案必須將 background-image 內容設為 url(images/custom-logo.png) 值,以參照標誌影像。
.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; }
- 為自訂作業檔案配置檔案監視。
您可以將自訂作業檔案儲存在預設位置,以進行自動監視,或者您可以變更伺服器配置,以定義您檔案的位置。如果指定了多個預設自訂作業檔案,您會看到一則送往主控台的警告訊息輸出,指出要監視的自訂作業檔案以及要忽略的檔案。選取要監視的自訂作業檔案會由 Liberty 持續監視,直到刪除它為止。
註: 只會監視自訂作業檔案是否有更新。不會監視 CSS 和標誌檔案。不會監視 URL。- 以 YAML、YML 或 JSON 檔案類型,將自訂作業 Snippet 儲存在 ${server.config.dir}/openapi/customization.file_type,以採用預設自訂作業檔案監視。
- 選擇性的: 在 Liberty 伺服器配置檔中新增 openapi 元素,並為元素指定 customization 屬性,以參照該 Snippet。
當明確設定 customization 屬性時,不會監視預設自訂作業定義位置。customization 屬性可以指定 YAML、YML 或 JSON 檔案,以交由 Liberty 監視。路徑可以包含執行時期目錄相關聯的 Liberty 變數,如下列範例所示。
<openapi customization="${server.config.dir}/custom/customInfo.yaml" />
customization 屬性也可以指定一個 URL,以傳回 OpenAPI Snippet。
<openapi customization="http://myWebsite.com/myCustomOpenAPI" />
- 選擇性的: 停用自訂作業檔案的檔案監視。
依預設,Liberty 會持續監視自訂作業檔案。不過,監視檔案時會使用額外的系統資源。如果您沒有任何自訂作業檔案,或者您的自訂作業檔案是靜態的且沒有變更,最好關閉檔案監視。
在您的伺服器配置檔中,將 openapi 元素的 disableFileMonitor 布林屬性設為 true。當 disableFileMonitor 屬性設為 true 時,也不會監視預設自訂作業定義位置。<openapi disableFileMonitor="true" />

檔名:twlp_api_openapi_custom.html