使用 OpenAPI 來產生 REST API 說明文件

您可以使用支援 OpenAPI 規格的 openapi-3.0 特性，來產生 REST API 說明文件。記載 REST API、指定公用和專用 API、選擇啟用註釋掃描，以及將 Web 應用程式部署至 Liberty 伺服器。之後您就可以在使用人類可讀使用者介面的瀏覽器中，檢視 openapi-3.0 產生的 API 說明文件。

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

如需搭配使用 MicroProfile OpenAPI 與 Liberty的相關資訊，請參閱 Open Liberty 網站

開始之前

瞭解 OpenAPI V3 規格。您可以使用 YAML 或 JSON 檔案，來記載您應用程式中的 RESTful API。

您可以使用 MicroProfile OpenAPI Specification 1.0中提供的 Java 介面和程式設計模型。 mpOpenAPI-1.0 特性會實作 MicroProfile OpenAPI 規格。如需 mpOpenAPI-1.0 及更新版本特性的相關資訊，請參閱使用 MicroProfile OpenAPI。

關於這項作業

您可以透過下列的範例應用程式，來探索這些特性，例如：新的使用者介面、註釋和程式設計介面。

嘗試使用 OpenAPI V3 註釋範例應用程式，在 Java™ 程式碼中使用 OpenAPI 註釋來記載 RESTful 應用程式。
請參閱 OpenAPI V3 文件的範例，該文件採用 YAML 格式，並使用 OpenAPI V3 範例文件以文字編輯器建立。
搭配使用 io.swagger.oas.integration.OpenAPIConfigurationBuilder 程式設計介面與 OpenAPIConfiguration 程式設計介面範例，以延伸 openapi-3.0 特性。

程序

建置 OpenAPI 說明文件。
您可以採用多種方式來記載和建置 OpenAPI：
- 在 Java 程式碼中指定 OpenAPI 註釋，以擴增及記載應用程式。
- 使用文字編輯器，來記載具有 OpenAPI 標籤的 API，然後將已完成的 openapi.yaml、openapi.yml 或 openapi.json 檔放在您應用程式的 META-INF 目錄中。
- 使用 io.swagger.oas.integration.OpenAPIConfigurationBuilder 程式設計介面，從應用程式內建置 OpenAPI 模型。這個介面以及適用於 OpenAPI 第 3 版的其他相關程式設計介面，可在 /wlp/dev/api/third-party 目錄中的 JAR 檔內找到。為了讓 openapi-3.0 特性能啟動 OpenAPIConfigurationBuilder，應用程式保存檔必須有一個 META-INF/services/io.swagger.oas.integration.OpenAPIConfigurationBuilder 檔。這個檔案的內容是 OpenAPIConfigurationBuilder 的完整名稱。
  如需可用程式設計介面、其功能說明及其使用範例的相關資訊，請參閱 OpenAPI V3 程式設計介面。
在 Liberty 伺服器配置中啟用 openapi-3.0 特性。
1. 將 openapi-3.0 特性新增至特性管理程式。
```
<server>
   <featureManager>
      <feature>openapi-3.0</feature>
   </featureManager>
</server>
```
2. 選用: 指定應用程式 OpenAPI 是專用的。
  
  依預設，OpenAPI 說明文件是公用的。所有使用者通常不需鑑別，就可以存取公用 API。公用 API 記載於 /api/docs 資源中。
  您可以指定 API 維持專用。管理用的 API 通常維持專用。使用密碼保護的專用 API 記載於 /ibm/api/docs 資源中。這個資源記載了所有專用 API 和所有公用 API。
  
  您可以採取下列兩種方式，為 Web 應用程式指定專用 API：
  - 在伺服器配置中使用 webModuleDoc，並將 public 屬性設為 false。
    1. 新增 openapi 元素，並將其 enablePrivateURL 布林屬性設為 true。
    2. 為每一個 Web 應用程式新增 webModuleDoc 子元素，並針對公用 API，將其 public 布林屬性設為 true，以及針對專用 API，將該屬性設為 false。
    下列範例是讓 airlines 應用程式 OpenAPI 變成可見，以及不要顯露 airlinesAdmin 應用程式 OpenAPI。
```
<openapi enablePrivateURL="true">
  <webModuleDoc contextRoot="/airlines" public="true" />
  <webModuleDoc contextRoot="/airlinesAdmin" public="false" />
</openapi>
```
    依預設，webModuleDoc 的 public 屬性設為 true。只有在您想停用要維持專用的應用程式時，才需要這項配置。
  - 在 API 說明中使用供應商延伸關鍵字，來指定該 API 是專用的。
    1. 新增 openapi 元素至伺服器配置，並將其 enablePrivateURL 布林屬性設為 true。
    2. 將 x-ibm-private: true 關鍵字和值放在 API 說明文件 META-INF/openapi.yaml 檔中，或放在另一個支援格式的檔案中。此值會置換 API 預設可見性，且這個值可能被 webModuleDoc 項目置換。
3. 選用: 指定應用程式不會出現在 OpenAPI 文件中。
  
  依預設，如果您的 Web 模組包含 REST API 文件，則會出現在合併的 OpenAPI 文件中（位於 /api/docs 資源內）。如果不想讓 Web 模組出現在 OpenAPI 文件中，請在伺服器配置中變更 webModuleDoc 元素的屬性。
  使用 contextRoot 屬性來識別您想隱藏或顯示的 Web 模組。然後將 enabled 屬性變更為 false，在 OpenAPI 文件中隱藏 Web 模組。 enabled 屬性的預設值是 true。下列範例是配置 airlines 模組，使它出現在 OpenAPI 文件中，同時隱藏 airlinesAdmin 模組。
```
<openapi>
  <webModuleDoc contextRoot="/airlines" enabled="true" />
  <webModuleDoc contextRoot="/airlinesAdmin" enabled="false" />
</openapi>
```
  附註: 其他 Liberty 特性所提供的 REST API 文件不支援 enabled 屬性。
選用: 啟用 JAX-RS 註釋掃描。

新增 jaxrs-2.0 特性至特性管理程式。當在伺服器中同時啟用 jaxrs-2.0 和 openapi-3.0 特性時，除非伺服器配置停用掃描，註釋掃描器會掃描部署在伺服器上的所有 Web 應用程式。掃描器會逐一掃描類別定義中標註了 OpenAPI 3.0 註釋以及標註了 @Path JAX-RS 註釋的所有類別。您可以使用 OpenAPI 公用端點 (api/docs) 和專用端點 (ibm/api/docs)，來存取產生的 OpenAPI 說明文件。
針對特定應用程式容許協力廠商 API 可見性。
如果希望能在執行時期載入 OpenAPI 註釋、模型和程式設計模型，您必須針對特定應用程式，啟用協力廠商 API 可見性。
1. 將 classloader 元素的 apiTypeVisibility 屬性定義為協力廠商 API 可見性。將 third-party 新增至 server.xml 檔中的 classloader 元素。
  
  如果您沒有指定 classloader 以便將 third-party 包含在 apiTypeVisibility 中，它會使用 spec、stable 和 ibm-api 預設定義。
```
<application id="scholar" name="Scholar" type="ear" location="scholar.ear">
  <classloader apiTypeVisibility="spec, ibm-api, stable, third-party" commonLibraryRef="Alexandria" />
</application>
```
選用項目: 啟用 OpenAPI 文件的驗證。

依預設，會停用驗證功能。一旦啟用驗證，則 openapi-3.0 特性會根據 OpenAPI 第 3 版規格中宣告的限制，來驗證應用程式提供的每一份 OpenAPI 說明文件。如果 openapi-3.0 找到無效的 OpenAPI 文件，此特性會在日誌中針對每一項違反的限制報告錯誤。在 api/docs 端點傳回的聚集 OpenAPI 文件中，會排除無效的文件。如果要啟用驗證，請在 server.xml 檔中，將 validation 屬性設為 true 。
```
<openapi validation="true"/>
```
部署應用程式。
在瀏覽器中檢視產生的 API 說明文件。
您可以利用下列其中一個 URL（視您的 API 是公用或專用而定），在 /api/docs 端點找到產生的 API 說明文件。
- 若為非 SSL 公用 API，可在 http://Liberty_host:http_port/api/docs 檢視您的文件。
- 若為 SSL 公用 API，可在 https://Liberty_host:https_port/api/docs 檢視您的文件。
- 若為 SSL 專用 API，可在 https://Liberty_host:https_port/ibm/api/docs 檢視您的文件。
提示: 依預設，伺服器有兩個端點可用。
- GET http://Liberty_host:http_port/api/docs
- GET http://Liberty_host:http_port/api/explorer
您可以使用 server.xml 檔案中的 publicURL 屬性來自訂公用端點的 URL。下列範例說明 server.xml 檔案中的配置，以讓 GET http://Liberty_host:http_port/myAPI/docs and http://Liberty_host:http_port/myAPI/explorer提供公用 REST API 文件。
```
<openapi publicURL="myAPI" />
```
針對該 Liberty 伺服器，在應用程式之間產生並聚集 OpenAPI 文件。依預設，文件是 YAML 格式。當您使用 Microsoft Internet Explorer 11 檢視文件時，它會傳回未適當格式化的 YAML 文件。暫行解決方法是使用 Mozilla Firefox 或 Google Chrome 瀏覽器之類的瀏覽器。如果 http 要求中的 Accept 標頭值是 application/json，則文件是 JSON 格式。

提示: 您可以依環境定義根目錄來過濾 OpenAPI 文件。公用端點 (api/docs) 和專用端點 (ibm/api/docs) 都支援 root 查詢參數，此參數可過濾找到的環境定義根目錄。例如，當呼叫 GET http://Liberty_host:http_port/api/docs?root=/myApp 時，則會擷取只含有 myApp 環境定義根目錄說明文件的 OpenAPI 第 3 版文件。

結果

「OpenAPI 使用者介面」會呈現 /api/docs 中的聚集定義，以便在 http://Liberty_host:http_port/api/explorer 顯示人類可讀的使用者介面。如果您啟用 SSL，可在 https://Liberty_host:https_port/api/explorer 存取受保護的使用者介面。

您可以在 server.xml 檔的 openAPI 元素中啟用 enablePrivateURL 屬性，來瀏覽專用 Web 模組。

<openapi enablePrivateURL="true"/>

當啟用專用 Web 模組瀏覽時，請使用 https://Liberty_host:https_port/ibm/api/explorer，以同時針對公用和專用 Web 模組，顯示人類可讀的使用者介面。

您可以在這個使用者介面中，檢視您應用程式中所有的 RESTful 端點。您也可以過濾顯示的端點，以聚焦在特定的應用程式。