您可以使用支援 OpenAPI 規格的 openapi-3.0 特性,來產生 REST API 說明文件。記載您的 REST API,指定公用和專用
API,選擇啟用註釋掃描,並將您的 Web 應用程式部署至
Liberty 伺服器。之後您就可以在使用人類可讀使用者介面的瀏覽器中,檢視
openapi-3.0 產生的 API 說明文件。
關於這項作業
您可以透過下列的範例應用程式,來探索這些特性,例如:新的使用者介面、註釋和程式設計介面。
程序
- 建置 OpenAPI 說明文件。
您可以採用多種方式來記載和建置 OpenAPI:
- 在 Liberty 伺服器配置中啟用 openapi-3.0 特性。
- 新增 openapi-3.0 特性至特性管理程式。
<server>
<featureManager>
<feature>openapi-3.0</feature>
</featureManager>
</server>
- 選擇性的: 指定應用程式 OpenAPI 是專用的。
依預設,OpenAPI 說明文件是公用的。所有使用者通常不需鑑別,就可以存取公用 API。公用 API 記載於
/api/docs 資源中。
您可以指定 API 維持專用。管理用的 API 通常維持專用。使用密碼保護的專用 API 記載於
/ibm/api/docs 資源中。這個資源記載了所有專用 API 和所有公用 API。
您可以採取下列兩種方式,為 Web 應用程式指定專用 API:
- 在伺服器配置中使用 webModuleDoc,並將 public
屬性設為 false。
- 新增 openapi 元素,並將其 enablePrivateURL 布林屬性設為 true。
- 為每一個 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 是專用的。
- 新增 openapi 元素至伺服器配置,並將其
enablePrivateURL 布林屬性設為 true。
- 將 x-ibm-private: true 關鍵字和值放在 API 說明文件
META-INF/openapi.yaml 檔中,或放在另一個支援格式的檔案中。此值會置換 API 預設可見性,且這個值可能被
webModuleDoc 項目置換。
- 選擇性的: 指定應用程式不要出現在 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 可見性。
- 將 classloader 元素的 apiTypeVisibility 屬性定義成協力廠商
API 可見性。將 third-party 新增至 server.xml 檔中的
classloader 元素。
如果您沒有指定 classloader 以便將 third-party 包含在
apiTypeVisibility 中,它會使用 spec 和
ibm-api 預設定義。
<application id="scholar" name="Scholar" type="ear" location="scholar.ear">
<classloader apiTypeVisibility="spec, ibm-api, 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 和
http://Liberty_host:http_port/myAPI/explorer,提供公用 REST API 說明文件。
<openapi publicURL="myAPI" />
OpenAPI 文件是針對該 Liberty 伺服器,跨多個應用程式來產生及聚集的。依預設,文件是 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 端點。您也可以過濾顯示的端點,以聚焦在特定的應用程式。