自訂 OpenAPI 說明文件

您可以針對位於 /api/docs 端點的主要 OpenAPI 文件以及位於 /api/explorer 的 OpenAPI 使用者介面，使用 externalDocs 和 info 等元素，來自訂其各個層面。 Liberty 會監視預設路徑位置的自訂作業檔案變更，以處理及更新主要 OpenAPI 文件和使用者介面的變更。

已穩定的特性: OpenAPI V3 特性 openapi-3.0 和 openapi-3.1已穩定。您可以繼續使用這些特性。不過，策略性替代方案是使用 MicroProfile OpenAPI 特性，例如 mpOpenAPI-3.0。

開始之前

若要瞭解如何建置及啟用 OpenAPI 文件，請參閱使用 OpenAPI 產生 REST API 文件。

使用範例 OpenAPI V3 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 開頭的元素。
- 只會使用在以 .swagger-ui .headerbar 開頭的 CSS 元素下指定的內容。
- CSS 檔案所參照之自訂標誌檔案必須是 PNG 格式。
- 自訂標誌檔案必須命名為 custom-logo.png，並且放在 images/custom-logo.png 中。
- 標誌檔案路徑必須相對於 CSS 檔案。
- CSS 檔案必須將 background-image 內容設為 url(images/custom-logo.png) 值，以參照標誌影像。
下列的範例 Snippet 顯示置換用的 CSS 檔案。
```
.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。
1. 將自訂作業 Snippet 儲存在 ${server.config.dir}/openapi/customization.file_type 中的 YAML、YML 或 JSON 檔案類型，以使用預設自訂作業檔案監視。
2. 選用: 新增 openapi 元素，其中的 customization 屬性會參照 Liberty 伺服器配置檔中的 Snippet。
  
  當明確設定 customization 屬性時，不會監視預設自訂作業定義位置。 customization 屬性可以指定由 Liberty監視的 YAML、YML 或 JSON 檔案。路徑可以包含與執行時期目錄相關聯的 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" />
```