[17.0.0.3 and later]

OpenAPI V3 プログラミング・インターフェース

以下のプログラミング・インターフェースを使用して、openapi-3.0 フィーチャーを拡張できます。GitHub にある OpenAPI V3 サンプル・アプリケーションを参照して、独自の OpenAPI モデルの作成とドキュメンテーションの生成を行ってください。

Application programming interfaces (API)

io.swagger.oas.integration プログラミング・インターフェースを使用して、Liberty での OpenAPI V3 処理に関連するパラメーターを構成できます。これらのパラメーターは、/wlp/dev/api/third-party ディレクトリー内の JAR ファイルに入っています。

OpenAPIConfiguration
io.swagger.oas.integration.OpenAPIConfiguration インターフェースは、 OpenAPI V3 処理におけるすべての構成パラメーターのコンテナーです。このインターフェースを使用して、完全な OpenAPI モデルを提供したり、アノテーションのスキャンを無効化または構成したり、他のヘルパー・サービスを提供したりすることができます。 これらのサービスには、カスタム・リーダーおよびスキャナーが含まれています。
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 V3 処理のカスタマイズを有効にするメイン・サービスです。OpenAPIConfigurationBuilder を使用して、新規 OpenAPIConfiguration オブジェクト作成時に処理する、フレームワークに依存する環境変数を受け取ることができます。
public interface OpenAPIConfigurationBuilder {
   OpenAPIConfiguration build(Map<String, Object> environment);
}

次のコード例は、OpenAPIConfigurationBuilder を使用して、OpenAPI V3 サンプル・アプリケーションと共に 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);
}

指定された OpenAPIReaderopenapi-3.0 フィーチャーが実装するには、アプリケーション・アーカイブに 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 V3 文書を提供するためのインターフェースを導入します。SPI ユーザーは、アプリケーション・ベースの拡張機能または製品拡張機能である OSGi バンドルの OpenAPI V3 文書を生成できます。これらの SPI は /wlp/dev/spi/ibm ディレクトリー内にあります。文書を生成するには、com.ibm.wsspi.openapi.OASProvider インターフェースの実装を OSGi フレームワークに登録します。

OASProviderConfig
OASProviderConfig は、特定の OpenAPI V3 文書にリンクできる、サポート・オプションのヘルパー・クラスです。OASProviderConfig を使用して、文書が記述される言語を指定できます。
制約事項: openapi-3.0 が文書を生成するときには、OASProvider から返された最初の結果のみが使用されます。openapi-3.0 は、複数の言語用の OASProvider 構成をサポートしません。結果を 1 つだけ返すプロバイダーを指定してください。
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 String としてフォーマットされた YAML テキストまたは JSON テキストのいずれかを使用することによって、単一の OpenAPI V3 文書を返します。これには、文書に関するメタデータを提供するための構成が付加されます。
public interface OASProviderResult {
    OpenAPI getOpenAPI();
    String getDocument();
    OASProviderConfig getOASProviderConfig();
}
OASProvider
このインターフェースは、OpenAPI フィーチャーに文書を提供するために SPI ユーザーが実装する必要のあるメイン・サービスです。文書を生成するには、文書化したいコンテキスト・ルートごとに 1 つの OASProvider を登録する必要があります。
public interface OASProvider {
    List<OASProviderResult> getResults();
    String getContextRoot();
    boolean isPublic()     
    };
}

トピックのタイプを示すアイコン 参照トピック

ファイル名: rwlp_api_openapi_interfaces.html