OpenAPI 第 3 版程式設計介面

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

應用程式設計介面 (API)
服務程式設計介面 (SPI)

已穩定的特性: OpenAPI V3 特性 openapi-3.0 和 openapi-3.1已穩定。您可以繼續使用這些特性。不過，策略性替代方案是使用 MicroProfile OpenAPI 特性，例如 mpOpenAPI-3.0。

應用程式設計介面 (API)

您可以使用 io.swagger.oas.integration 程式設計介面來配置與 Liberty中的 OpenAPI V3 處理相關的參數。這些參數位於 /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.util.ServiceLoader上的 Java™ SE 說明文件。

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 V3 文件。它含有一項附加的配置，以提供文件的相關 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()     
    };
}