您可以使用支援 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 說明文件。
- 在 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
、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 端點。 您也可以過濾顯示的端點,以聚焦在特定的應用程式。