Swaggerを使用してSpringBootRESTクライアントを生成する

投稿日: 2019-10-18 2022-10-11
タグ: REST, Spring Boot, Swagger

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で利用可能なコードを見つけることができます。

getdocs

13036