![[17.0.0.3 以及更新版本]](../ng_v17003plus.gif)
OpenAPI 第 3 版程式設計介面
應用程式設計介面 (API)
您可以使用 io.swagger.oas.integration 程式設計介面,在 Liberty 中配置 OpenAPI 第 3 版處理程序的相關參數。這些參數位於 /wlp/dev/api/third-party 目錄中的 JAR 檔內。
- OpenAPIConfiguration
- io.swagger.oas.integration.OpenAPIConfiguration 介面是一個儲存器,用來儲存
OpenAPI 第 3 版處理程序中的所有配置參數。利用這個介面,您可以提供完整的 OpenAPI 模型、停用或配置註釋掃描,以及提供其他的
helper 服務。這些服務包括自訂讀取器和掃描器。
public interface OpenAPIConfiguration { Set<String> getResourcePackages(); Set<String> getResourceClasses(); String getReaderClass(); String getScannerClass(); Collection<String> getIgnoredRoutes(); OpenAPI getOpenAPI(); Map<String, Object> getUserDefinedOptions(); Boolean isReadAllResources(); Boolean isScanningDisabled(); }
- OpenAPIConfigurationBuilder
- io.swagger.oas.integration.OpenAPIConfigurationBuilder 介面是主要服務,可讓您在 Liberty 中自訂 OpenAPI
第 3 版處理程序。您可以使用
OpenAPIConfigurationBuilder 來接收與架構相依的環境變數,以供它在建置新的
OpenAPIConfiguration 物件時處理。
public interface OpenAPIConfigurationBuilder { OpenAPIConfiguration build(Map<String, Object> environment); }
下列範例程式碼使用 OpenAPIConfigurationBuilder,以利用 OpenAPI 第 3 版範例應用程式來建置一個 OpenAPI 模型。
package com.example; public final class AirlinesAPIs implements OpenAPIConfigurationBuilder { private OpenAPIConfiguration configuration = new OpenAPIConfiguration() { @Override public Boolean isScanningDisabled() { return Boolean.FALSE; } @Override public Boolean isReadAllResources() { return Boolean.TRUE; } @Override public Map<String, Object> getUserDefinedOptions() { return null; } @Override public String getScannerClass() { return "com.example.OpenAPIScannerImpl"; } @Override public Set<String> getResourcePackages() { return null; } @Override public Set<String> getResourceClasses() { return null; } @Override public String getReaderClass() { return "com.example.OpenAPIReaderImpl"; } @Override public OpenAPI getOpenAPI() { OpenAPI oai = new OpenAPI().info(new Info().title("Airlines").version("1.0.0")).paths(new Paths() .addPathItem("/airlines", new PathItem().get(new Operation() .description("Get the list of available airlines").responses( new ApiResponses().addApiResponse("200", new ApiResponse().description("successful") .content(new Content().addMediaType("application/json", new MediaType() .schema(new Schema().$ref("#/components/schemas/Airlines"))))))))); return oai; } @Override public Collection<String> getIgnoredRoutes() { return null; } }; @Override public OpenAPIConfiguration build(Map<String, Object> environment) { return configuration; } }
為了讓 openapi-3.0 特性能啟動 OpenAPIConfigurationBuilder,應用程式保存檔必須有一個 META-INF/services/io.swagger.oas.integration.OpenAPIConfigurationBuilder 檔。這個檔案的內容是 OpenAPIConfigurationBuilder 介面實作的完整名稱。就本例而言,其值是 com.example.AirlinesAPIs。如需這個檔案格式的相關資訊,請參閱 Java™ SE java.util.ServiceLoader 說明文件。
- OpenAPIReader
- io.swagger.oas.integration.OpenAPIReader 介面可讓應用程式開發人員提供自訂
JAX-RS 讀取器,而非提供 JAX-RS 讀取器預設實作。當您啟用 OpenAPIReader 服務時,您可以自訂執行時期伺服器該如何處理類別和資源。
public interface OpenAPIReader { void setConfiguration(OpenAPIConfiguration openAPIConfiguration); OpenAPI read(Set<Class<?>> classes, Map<String, Object> resources); }
為了讓 openapi-3.0 特性實作指定的 OpenAPIReader,應用程式保存檔必須有一個 META-INF/services/io.swagger.oas.integration.OpenAPIReader 檔。這個檔案含有 OpenAPIReader 介面實作的完整名稱。
您也可以使用 io.swagger.oas.integration.OpenAPIConfiguration.getReaderClass(),來指定實作類別的完整名稱。
- OpenAPIScanner
- 您可以使用
io.swagger.oas.integration.OpenAPIScanner,來配置 JAX-RS
讀取器要處理哪些類別和資源。如果啟用這項服務,Liberty 會置換註釋掃描。
public interface OpenAPIScanner { void setConfiguration(OpenAPIConfiguration openAPIConfiguration); Set<Class<?>> getClasses(); Map<String, Object> getResources(); }
類似於 OpenAPIConfigurationBuilder 和 OpenAPIReader 兩者,應用程式保存檔也必須包含 META-INF/service/io.swagger.oas.integration.OpenAPIScanner 檔。這個檔案含有 OpenAPIScanner 介面實作的完整名稱。
您也可以使用 io.swagger.oas.integration.OpenAPIConfiguration.getReaderClass(),來指定實作類別的完整名稱。
服務程式設計介面 (SPI)
openapi-3.0 特性引進了一個 OSGi 軟體組介面,來提供 API 的 OpenAPI 第 3 版說明文件。SPI 使用者可以針對以應用程式為基礎或作為產品延伸的 OSGi 軟體組,產生 OpenAPI 第 3 版說明文件。您可以在 /wlp/dev/spi/ibm 目錄中找到這些 SPI。如果要提供您的說明文件,請將 com.ibm.wsspi.openapi.OASProvider 介面實作登錄到 OSGi 架構。
- OASProviderConfig
- OASProviderConfig 是支援選項的 helper 類別,可鏈結至特定的
OpenAPI 第 3 版文件。您可以使用 OASProviderConfig,指定您撰寫文件時使用的語言。限制: 在 openapi-3.0 產生說明文件時,只會使用 OASProvider 傳回的第一筆結果。openapi-3.0 不支援多種語言的 OASProvider 配置。請指定只會傳回一筆結果的提供者。
public final class OASProviderConfig { private String language; public String getLanguage() { return this.language; } public void setLanguage(String language) { this.language = language; } @Override public boolean equals(Object o) { if (o == null || getClass() != o.getClass()) { return false; } OASProviderConfig config = (OASProviderConfig) o; return Objects.equals(this.language, config.language); } @Override public int hashCode() { return Objects.hash(this.language); } public static OASProviderConfig defaultConfig() { return new OASProviderConfig(); } }
- OASProviderResult
- OASProviderResult 介面會使用 OpenAPI 模型或
Java 字串格式的 YAML 或 JSON 文字,來傳回單一 OpenAPI 第 3 版文件。它含有一項附加的配置,以提供文件的相關 meta 資料。
public interface OASProviderResult { OpenAPI getOpenAPI(); String getDocument(); OASProviderConfig getOASProviderConfig(); }
- OASProvider
- 這個介面是 SPI 使用者必須實作的主要服務,以便在其 OpenAPI 第 3 版特性中提供說明文件。如果要提供說明文件,您必須針對您想記載的每一個環境定義根目錄,各登錄一個
OASProvider。
public interface OASProvider { List<OASProviderResult> getResults(); String getContextRoot(); boolean isPublic() }; }