mpOpenAPI-1.0 特性提供 MicroProfile
OpenAPI 規格 1.0 版的實作以及一組 Java 介面和程式設計模型,可讓
Java 開發人員從其 JAX-RS 應用程式,以原本方式產生 OpenAPI 第 3 版文件。之後,您可以在使用人類可讀之使用者介面的瀏覽器中,檢視以
mpOpenAPI-1.0 特性產生的 API 說明文件。
開始之前
瞭解
OpenAPI 第 3 版規格和
MicroProfile OpenAPI 1.0 規格。您可以使用 YAML 格式或 JSON 格式的靜態
OpenAPI 檔案、MicroProfile OpenAPI 註釋或 OpenAPI
程式設計模型,來記載您應用程式中的 RESTful API。
避免困難: - 只有作業層次和類別層次支援延伸和延伸註釋。對於其他元素,請使用其他說明文件機制來指定延伸。
- 如果您第一次輸入的授權認證不正確,則 OpenAPI 使用者介面的行為將不符合預期。如果您之後輸入正確的認證,則問題仍在,且可能反覆地提示您提供認證。請重新整理頁面,並輸入正確的認證。
- 如果在啟用 mpOpenAPI-1.0 之後,啟用 ssl-1.0 特性,當您存取 /openapi 或
openapi/ui 端點時,可能會導致異常狀況。如果要避免發生問題,請一起啟用這兩項特性。在問題發生之後,如果要解決,請停用再啟用
mpOpenAPI-1.0 特性。
如果部署了多個應用程式,則會選取其中一個應用程式來產生 OpenAPI 說明文件。會輸出參考訊息,以識別所選取的應用程式。如果選取的應用程式正在執行,應用程式處理器會忽略其他所有的應用程式。當選取的應用程式停止之後,會處理下一個應用程式。
程序
- 選擇性的: 如果您應用程式需要,請透過 MicroProfile
配置機制,來配置 MicroProfile OpenAPI 規格中的不同部分。 當啟動應用程式時,mpOpenAPI-1.0 特性會讀取所配置的值。
- 為您的應用程式,配置 MicroProfile OpenAPI 規格所提供的一或多項核心配置。
- 如果要新增值,mpOpenAPI-1.0 特性會驗證產生給應用程式的最終
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 模型之後加以更新。
- 在 Liberty 伺服器配置中,啟用 mpOpenAPI-1.0 特性。
<server>
<featureManager>
<feature>mpOpenAPI-1.0</feature>
</featureManager>
</server>
- 部署應用程式。
- 選擇性的: 檢查驗證結果,並確定您的應用程式符合 OpenAPI 規格 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 存取受保護的使用者介面。