[17.0.0.3 以及更新版本]

OpenAPI 第 3 版程式設計介面

您可以使用下列程式設計介面,來延伸 openapi-3.0 特性。請參閱 GitHub 上的 OpenAPI 第 3 版範例應用程式,來建置您自己的 OpenAPI 模型,並產生說明文件。

應用程式設計介面 (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();
}

類似於 OpenAPIConfigurationBuilderOpenAPIReader 兩者,應用程式保存檔也必須包含 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()     
    };
}

指示主題類型的圖示 參照主題

檔名:rwlp_api_openapi_interfaces.html