Swaggerを使用してSpringBootRESTクライアントを生成する
1. 序章
この記事では、 SwaggerCodegenおよびOpenAPIGenerator プロジェクトを使用して、 OpenAPI/Swagger仕様ファイルからRESTクライアントを生成します。
また、生成されたクラスを使用するSpring Bootプロジェクトを作成します。
すべてにSwaggerPetstoreAPIの例を使用します。
2. SwaggerCodegenを使用してRESTクライアントを生成する
Swaggerは、さまざまなプログラミング言語および複数のフレームワーク用のRESTクライアントを生成できるユーティリティjarを提供します。
2.1. Jarファイルをダウンロード
code-gen_cli.jar は、こちらからダウンロードできます。
最新バージョンについては、swagger-codegen-cliリポジトリを確認してください。
2.2. クライアントを生成する
コマンドjava-jar swagger-code-gen-cli.jar generate:を実行して、クライアントを生成しましょう。
java -jar swagger-codegen-cli.jar generate \
-i http://petstore.swagger.io/v2/swagger.json \
--api-package com.baeldung.petstore.client.api \
--model-package com.baeldung.petstore.client.model \
--invoker-package com.baeldung.petstore.client.invoker \
--group-id com.baeldung \
--artifact-id spring-swagger-codegen-api-client \
--artifact-version 0.0.1-SNAPSHOT \
-l java \
--library resttemplate \
-o spring-swagger-codegen-api-client
提供される引数は次のもので構成されます。
- ソースSwaggerファイルのURLまたはパス– -i引数を使用して提供
- 生成されたクラスのパッケージ名– –api-package 、 –model-package 、 –invoker-packageを使用して提供
- 生成されたMavenプロジェクトのプロパティ–group-id 、 –artifact-id 、 –artifact-version
- 生成されたクライアントのプログラミング言語– -lを使用して提供
- 実装フレームワーク– –libraryを使用して提供
- 出力ディレクトリ– -oを使用して提供
Java関連のすべてのオプションを一覧表示するには、次のコマンドを入力します。
java -jar swagger-codegen-cli.jar config-help -l java
Swagger Codegenは、次のJavaライブラリ(HTTPクライアントとJSON処理ライブラリのペア)をサポートしています。
- jersey1 –Jersey1+ジャクソン
- jersey2 –Jersey2+ジャクソン
- feign – OpenFeign + Jackson
- okhttp-gson – OkHttp + Gson
- レトロフィット(廃止)– Retrofit1 / OkHttp + Gson
- retrofit2 – Retrofit2 / OkHttp + Gson
- rest-template – Spring RestTemplate + Jackson
- rest-easy – Resteasy + Jackson
この記事では、Springエコシステムの一部であるrest-templateを選択しました。
3. OpenAPIジェネレーターを使用してRESTクライアントを生成する
OpenAPI Generatorは、OpenAPI仕様2.0/3.xドキュメントから50以上のクライアントを生成できるSwaggerCodegenのフォークです。
Swagger CodegenはSmartBearによって維持されていますが、OpenAPI Generatorは、SwaggerCodegenのトップコントリビューターとテンプレート作成者の40人以上を創設チームメンバーとして含むコミュニティによって維持されています。
3.1. インストール
おそらく、最も簡単で移植性の高いインストール方法は、 npmパッケージラッパーを使用することです。これは、Javaコードでサポートされているコマンドラインオプションの上にCLIラッパーを提供することで機能します。 インストールは簡単です。
npm install @openapitools/openapi-generator-cli -g
JARファイルが必要な場合は、 MavenCentralにあります。 今すぐダウンロードしましょう:
wget https://repo1.maven.org/maven2/org/openapitools/openapi-generator-cli/4.2.3/openapi-generator-cli-4.2.3.jar \
-O openapi-generator-cli.jar
3.2. クライアントを生成する
まず、OpenAPI Generatorのオプションは、SwaggerCodegenのオプションとほぼ同じです。 最も顕著な違いは、-l言語フラグが-gジェネレーターフラグに置き換えられたことです。このフラグは、言語を使用してクライアントをパラメーターとして生成します。
次に、jarコマンドを使用してSwaggerCodegenで生成したクライアントと同等のクライアントを生成しましょう。
java -jar openapi-generator-cli.jar generate \
-i http://petstore.swagger.io/v2/swagger.json \
--api-package com.baeldung.petstore.client.api \
--model-package com.baeldung.petstore.client.model \
--invoker-package com.baeldung.petstore.client.invoker \
--group-id com.baeldung \
--artifact-id spring-openapi-generator-api-client \
--artifact-version 0.0.1-SNAPSHOT \
-g java \
-p java8=true \
--library resttemplate \
-o spring-openapi-generator-api-client
Java関連のすべてのオプションを一覧表示するには、次のコマンドを入力します。
java -jar openapi-generator-cli.jar config-help -g java
OpenAPI Generatorは、SwaggerCodeGenと同じJavaライブラリをすべてサポートします。 次のJavaライブラリ(HTTPクライアントとJSON処理ライブラリのペア)がOpenAPIGeneratorでサポートされています。
- jersey1 –Jersey1+ジャクソン
- jersey2 –Jersey2+ジャクソン
- feign – OpenFeign + Jackson
- okhttp-gson – OkHttp + Gson
- レトロフィット(廃止)– Retrofit1 / OkHttp + Gson
- retrofit2 – Retrofit2 / OkHttp + Gson
- resttemplate – Spring RestTemplate + Jackson
- webclient – Spring 5 WebClient + Jackson(OpenAPIジェネレーターのみ)
- resteasy – Resteasy + Jackson
- vertx –VertX+ジャクソン
- google-api-client –GoogleAPIクライアント+ジャクソン
- 安心–安心+ Jackson / Gson(Java 8のみ)
- native –JavaネイティブHttpClient+ Jackson(Java11のみ;OpenAPIジェネレーターのみ)
- microprofile –マイクロプロファイルクライアント+ Jackson(OpenAPIジェネレーターのみ)
4. SpringBootProjectを生成する
新しいSpring Bootプロジェクトを作成しましょう。
4.1. Mavenの依存関係
まず、生成されたAPIクライアントライブラリの依存関係をプロジェクトpom.xmlファイルに追加します。
<dependency>
<groupId>com.baeldung</groupId>
<artifactId>spring-swagger-codegen-api-client</artifactId>
<version>0.0.1-SNAPSHOT</version>
</dependency>
4.2. APIクラスをSpringBeanとして公開する
生成されたクラスにアクセスするには、それらをBeanとして構成する必要があります。
@Configuration
public class PetStoreIntegrationConfig {
@Bean
public PetApi petApi() {
return new PetApi(apiClient());
}
@Bean
public ApiClient apiClient() {
return new ApiClient();
}
}
4.3. APIクライアント構成
ApiClient クラスは、認証、APIのベースパス、共通ヘッダーの構成に使用され、すべてのAPIリクエストの実行を担当します。
たとえば、OAuthを使用している場合:
@Bean
public ApiClient apiClient() {
ApiClient apiClient = new ApiClient();
OAuth petStoreAuth = (OAuth) apiClient.getAuthentication("petstore_auth");
petStoreAuth.setAccessToken("special-key");
return apiClient;
}
4.4. 春の主な用途
新しく作成した構成をインポートする必要があります。
@SpringBootApplication
@Import(PetStoreIntegrationConfig.class)
public class PetStoreApplication {
public static void main(String[] args) throws Exception {
SpringApplication.run(PetStoreApplication.class, args);
}
}
4.5. APIの使用法
APIクラスをBeanとして構成したので、Spring管理のクラスに自由に挿入できます。
@Autowired
private PetApi petApi;
public List<Pet> findAvailablePets() {
return petApi.findPetsByStatus(Arrays.asList("available"));
}
5. 代替ソリューション
SwaggerCodegenまたはOpenAPIGeneratorCLIを実行する以外に、RESTクライアントを生成する方法は他にもあります。
5.1. Mavenプラグイン
pom.xmlで簡単に構成できるswagger-codegenMavenプラグインを使用すると、SwaggerCodegenCLIと同じオプションでクライアントを生成できます。
これは、クライアントを自動的に生成するためにプロジェクトのpom.xmlに含めることができる基本的なコードスニペットです。
<plugin>
<groupId>io.swagger</groupId>
<artifactId>swagger-codegen-maven-plugin</artifactId>
<version>2.2.3</version>
<executions>
<execution>
<goals>
<goal>generate</goal>
</goals>
<configuration>
<inputSpec>swagger.yaml</inputSpec>
<language>java</language>
<library>resttemplate</library>
</configuration>
</execution>
</executions>
</plugin>
5.2. Swagger Codegen Online Generator API
他のオプションと一緒にスペックURLを渡すURLhttp://generator.swagger.io/api/gen/clients/java にPOSTリクエストを送信することにより、クライアントの生成に役立つ、すでに公開されているAPIリクエスト本文で。
簡単なcurlコマンドを使用して例を見てみましょう。
curl -X POST -H "content-type:application/json" \
-d '{"swaggerUrl":"http://petstore.swagger.io/v2/swagger.json"}' \
http://generator.swagger.io/api/gen/clients/java
応答は、生成されたクライアントコードをzip形式で含むダウンロード可能なリンクを含むJSON形式になります。 Swaager Codegen CLIで使用されているのと同じオプションを渡して、出力クライアントをカスタマイズできます。
https://generator.swagger.io には、APIのSwaggerドキュメントが含まれており、ドキュメントを確認して試すことができます。
5.3. OpenAPIジェネレーターオンラインジェネレーターAPI
Swagger Godegenと同様に、OpenAPIGeneratorにもオンラインジェネレーターがあります。 簡単なcurlコマンドを使用して例を実行してみましょう。
curl -X POST -H "content-type:application/json" \
-d '{"openAPIUrl":"http://petstore.swagger.io/v2/swagger.json"}' \
http://api.openapi-generator.tech/api/gen/clients/java
JSON形式の応答には、zip形式で生成されたクライアントコードへのダウンロード可能なリンクが含まれます。 Swagger Codegen CLIで使用されているのと同じオプションを渡して、出力クライアントをカスタマイズできます。
https://github.com/OpenAPITools/openapi-generator/blob/master/docs/online.md には、APIのドキュメントが含まれています。
6. 結論
SwaggerCodegenとOpenAPIGeneratorを使用すると、多くの言語と選択したライブラリを使用して、API用のRESTクライアントをすばやく生成できます。 CLIツール、Mavenプラグイン、またはオンラインAPIを使用してクライアントライブラリを生成できます。
これは、生成されたSwagger APIクライアント、生成されたOpenAPIクライアント、およびSpringBootアプリケーションの3つのMavenモジュールを含むMavenベースのプロジェクトです。
いつものように、GitHubで利用可能なコードを見つけることができます。