mpOpenAPI-1.1
特性提供 MicroProfile OpenAPI 規格的實作以及一組 Java 介面和程式設計模型,可讓 Java 開發人員從其 JAX-RS 應用程式,以原本方式產生 OpenAPI 第 3 版文件。 之後,您可以在使用人類可讀之使用者介面的瀏覽器中,檢視以 mpOpenAPI-1.1
特性產生的 API 說明文件。
如需使用 Liberty MicroProfile OpenAPI 特性 1.0 版以及更新版本的相關資訊,請參閱 Open Liberty 網站
開始之前
瞭解 OpenAPI V3 規格 ,以及 MicroProfile OpenAPI 1.1 規格 或 MicroProfile OpenAPI 1.0 規格。 您可以使用 YAML 格式或 JSON 格式的靜態
OpenAPI 檔案、MicroProfile OpenAPI 註釋或 OpenAPI
程式設計模型,來記載您應用程式中的 RESTful API。避免麻煩:
- 只有作業層次和類別層次支援延伸和延伸註釋。 對於其他元素,請使用其他說明文件機制來指定延伸。
- 如果您第一次輸入的授權認證不正確,則 OpenAPI 使用者介面的行為將不符合預期。 如果您之後輸入正確的認證,則問題仍在,且可能反覆地提示您提供認證。 請重新整理頁面,並輸入正確的認證。
- 如果在啟用
mpOpenAPI-1.1
之後,啟用 transportSecurity-1.0
特性,當您存取 /openapi 或 openapi/ui 端點時,可能會導致異常狀況。 如果要避免發生問題,請一起啟用這兩項特性。 在問題發生之後,如果要解決,請停用再啟用 mpOpenAPI
特性。
如果部署了多個應用程式,則會選取其中一個應用程式來產生 OpenAPI 說明文件。 會輸出參考訊息,以識別所選取的應用程式。 如果選取的應用程式正在執行,應用程式處理器會忽略其他所有的應用程式。 當選取的應用程式停止之後,會處理下一個應用程式。
程序
- 選用: 視您應用程式的需要,透過 MicroProfile config 機制,來配置 MicroProfile OpenAPI 規格的各種組件。
當啟動應用程式時,
mpOpenAPI-1.1
特性會讀取所配置的值。
- 針對您的應用程式,配置 MicroProfile OpenAPI 規格中提供的一或多個 核心配置 。
- 如果要新增值,
mpOpenAPI-1.1
特性會驗證產生給應用程式的最終 OpenAPI 文件,看看是否符合「OpenAPI 規格 3.0 版」中所宣告的各項限制。 驗證結果(錯誤和警告的組合)會輸出至主控台日誌。依預設,會為應用程式啟用驗證。 您可以設定下列配置,來停用驗證。
mp.openapi.extensions.liberty.validation=false
- 選擇下列其中一種或組合來提供輸入,以便依照 說明文件機制中的說明來產生所產生的 OpenAPI 文件。
- 使用 程式設計模型 來提供引導或完整 OpenAPI 模型樹狀結構。
- 使用文字編輯器以 YAML 或 JSON 格式撰寫 靜態 OpenAPI 文件 ,然後將 openapi.yaml、 openapi.yml或 openapi.json 檔案放置在應用程式的 META-INF 目錄中。
- 在 Java 程式碼中指定 MicroProfile OpenAPI 註釋 ,以擴增及記載應用程式。
- 在使用文件機制建置 OpenAPI 模型之後,請使用 filter 來更新它。
- 在 Liberty 伺服器配置中啟用
mpOpenAPI-1.1
特性。
<server>
<featureManager>
<feature>mpOpenAPI-1.1</feature>
</featureManager>
</server>
- 部署應用程式。
- 選用項目: 請檢查驗證結果,並確定您的應用程式符合 OpenAPI Specification 3.0版。
- 檢查主控台日誌中是否有驗證錯誤。
- 事件會分組成錯誤和警告。 訊息還包含所產生之文件中的對應位置,以利您識別相關的元素。
範例訊息:
CWWKO1650E: Validation of the OpenAPI document produced the following error(s):
- Message: Required "scopes" field is missing or is set to an invalid value, Location: #/components/securitySchemes/reviewoauth/flows/authorizationCode
- 在瀏覽器中檢視產生的 API 說明文件。
您可以使用下列其中一個 URL,來尋找在 /openapi 端點產生的 API 說明文件。
- 對於非 SSL 公用 API,請檢視位於
http://Liberty_host:http_port/openapi 的文件。
- 對於 SSL 公用 API,請檢視位於
https://Liberty_host:https_port/openapi 的文件。
結果
OpenAPI 使用者介面會呈現 /openapi 中的定義,以顯示位於
http://Liberty_host:http_port/openapi/ui 的使用者介面。 如果您啟用 SSL,可在
https://Liberty_host:https_port/openapi/ui 存取受保護的使用者介面。