TOC

SwaggerでSpring Boot RESTクライアントを生成する

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

1. 前書き

この記事では、Swagger CodeGenプロジェクトを使用して、OpenAPI/Swagger specファイルからRESTクライアントを生成します。

また、生成されたクラスを使用するSpringBootプロジェクトを作成します。

すべてにSwagger PetstoreAPIの例を使用します。

2. RESTクライアントを生成する

Swaggerは、さまざまなプログラミング言語および複数のフレームワーク用のRESTクライアントを生成できるユーティリティjarを提供します。

2.1. Jarファイルをダウンロードする

code-gen_cli.jarは、hereからダウンロードできます。

最新バージョンについては、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.example.petstore.client.api \
  --model-package com.example.petstore.client.model \
  --invoker-package com.example.petstore.client.invoker \
  --group-id com.example \
  --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 –ジャージー1+ジャクソン

  • jersey2 –ジャージー2+ジャクソン

  • feign – OpenFeign + Jackson

  • okhttp-gson – OkHttp + Gson

  • retrofit（廃止）– Retrofit1 / OkHttp + Gson

  • retrofit2 – Retrofit2 / OkHttp + Gson

  • rest-template – Spring RestTemplate +ジャクソン

  • rest-easy – Resteasy + Jackson

この記事では、Springエコシステムの一部であるrest-templateを選択しました。

3. SpringBootプロジェクトを生成する

それでは、新しいSpringBootプロジェクトを作成しましょう。

3.1. メーベン依存

まず、生成されたAPIクライアントライブラリの依存関係をプロジェクトのpom.xmlファイルに追加します。 


    com.example
    spring-swagger-codegen-api-client
    0.0.1-SNAPSHOT

3.2. APIクラスをSpringBeanとして公開する

生成されたクラスにアクセスするには、それらをBeanとして設定する必要があります。 

@Configuration
public class PetStoreIntegrationConfig {

    @Bean
    public PetApi petApi() {
        return new PetApi(apiClient());
    }

    @Bean
    public ApiClient apiClient() {
        return new ApiClient();
    }
}

3.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;
}

3.4. 春の主な用途

新しく作成した構成をインポートする必要があります。 

@SpringBootApplication
@Import(PetStoreIntegrationConfig.class)
public class PetStoreApplication {
    public static void main(String[] args) throws Exception {
        SpringApplication.run(PetStoreApplication.class, args);
    }
}

3.5. APIの使用法

APIクラスをBeanとして構成したので、Springが管理するクラスにそれらを自由に挿入できます。 

@Autowired
private PetApi petApi;

public List findAvailablePets() {
    return petApi.findPetsByStatus(Arrays.asList("available"));
}

4. 代替ソリューション

Swagger Codegen CLIを実行する以外に、RESTクライアントを生成する他の方法があります。

4.1. Mavenプラグイン

pom.xmlで簡単に構成できるswagger-codegen Maven pluginを使用すると、Swagger CodegenCLIと同じオプションを使用してクライアントを生成できます。

これは、クライアントを自動的に生成するためにプロジェクトのpom.xmlに含めることができる基本的なコードスニペットです。 


    io.swagger
    swagger-codegen-maven-plugin
    2.2.3
    
        
            
                generate
            
            
                swagger.yaml
                java
                resttemplate

4.2. オンラインジェネレータ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. 結論

Swagger Codegenを使用すると、多くの言語と選択したライブラリを使用して、API用のRESTクライアントを迅速に生成できます。 CLIツール、Mavenプラグイン、またはオンラインAPIを使用してクライアントライブラリを生成できます。

この例の実装は、このGitHub projectにあります。 これは2つのMavenモジュール、生成されたAPIクライアント、Spring Bootアプリケーションを含むMavenベースのプロジェクトです。

Related