![[17.0.0.3 and later]](../ng_v17003plus.gif)
OpenAPI V3 プログラミング・インターフェース
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); }
指定された OpenAPIReader を openapi-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(); }
OpenAPIConfigurationBuilder と OpenAPIReader の両方と同様、アプリケーション・アーカイブに 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() }; }