SpringfoxでSwaggerAPI仕様書を自動生成する（環境設定編）

はじめに

こんにちは。しがないOLのくにきちです。
あっという間に年末ですね。今回もクラスメソッドはお休み開始が早いので、今日で仕事納めです。
私はTwitterなどのアイコンを自作しているのですが、最近新作を描けてなかったので休み中に新しいアイコン描きたいなぁ、と思ってます。

そんなところで早速本題。 今回は「Springfox」というツールを使って、ソースコードから簡単に Web API仕様書を作成する方法を書いていきたいと思います。「環境設定編」と「仕様書カスタマイズ編」の全2回くらいで考えています。

まずは、今回のブログに出てくる Swagger と Springfox について簡単に説明。

Swagger とは

Swagger は、REST API を定義するためのオープンフレームワークです。
仕様を記述するためのルールを定め、Swagger Editor や Swagger UI など、設計や構築、ドキュメントの生成、テスト、デプロイなどを可能にするための関連ツールを提供しています。

Springfox とは

Swagger をベースに、Springで構築された API から Web API 仕様書を自動生成するためのツールです。アノテーションを用いてSwagger準拠のJSONを自動生成し、生成されたJSONからWebAPI仕様書を生成します。

本ブログの構成

• 前提
• ライブラリを追加する
• SwaggerConfigurationクラスを作成する
• SwaggerUIでAPI仕様書を表示する
• まとめ
• おわりに

前提

• Springfoxのバージョン : 2.0.7
• Springfoxの Swagger UI のバージョン : 2.2.10 (現在のSwagger UI バージョンは 3系なのでちょっと古い)

ライブラリを追加する

まずは、必要なライブラリを追加していきます。

build.gradle

compile 'io.swagger:swagger-annotations:1.5.16'
compile "io.springfox:springfox-swagger2:$springfoxVersion"
compile "io.springfox:springfox-swagger-ui:$springfoxVersion"

追加したライブラリは、以下のような役割があります。

swagger-annotations

Swaggerドキュメントをカスタマイズするためのアノテーションを定義しているライブラリです。

ソースコードにSwaggerアノテーションを付与して、API に関する説明を追加するなどSwaggerドキュメントをカスタマイズできます。次回の「仕様書カスタマイズ編」で大活躍します。

springfox-swagger2

Swaggerの設定を有効化し、Swagger準拠のJSONを生成します。

@EnableSwagger2 を SwaggerConfigurationクラス(後述)に付与することで必要なBeanをロードし、Swaggerのサポートを有効にします。 bootRun でアプリケーションを起動後、 http://localhost:8080/v2/api-docs にアクセスすると生成されたJSONを確認できます。

このライブラリは、以下のコンポーネントで構成されています。

• springfox-spi : 使用可能な拡張プラグインなどを使用できるようにします。
• springfox-schema : パラメータ、モデル、レスポンスのスキーマを構築します。
• springfox-swagger-common : Swaggerアノテーションを認識するための拡張機能。
• springfox-spring-web : RequestMapping情報に基づいてサービスモデルを構築します。
• springfox-core : 内部サービス、スキーマ記述モデル、ビルダーを保有し、JSONを生成します。

springfox-swagger-ui

springfox-swagger2 により生成された JSON から Web API 仕様書を生成します。

bootRun でアプリケーションを起動後、http://localhost:8080/swagger-ui.html で生成した Web API 仕様書を確認できます。

API仕様書生成イメージ

SwaggerConfigurationクラスを作成する

Swaggerドキュメントを定義するクラスとして SwaggerConfiguration.java を作成します。このクラスでは、サービスを文書化するための Docket インスタンスを生成し、Docket が持つメソッドを用いてSwaggerドキュメントを定義します。

Docket の定義

Docketは多くのメソッドを用意しています。今回はその一部をご紹介します。

SwaggerConfigurationの例

@EnableSwagger2
@Configuration
public class SwaggerConfiguration {

    @Bean
    public Docket restApi() {
        return new Docket(DocumentationType.SWAGGER_2)
            .produces(newHashSet("application/json"))
            .apiInfo(apiInfo()) // (1)
            .select()
            .paths(paths()) // (2)
            .build()
            .securitySchemes(securityScheme()) // (3)
            .enableUrlTemplating(false)
            .genericModelSubstitutes(Optional.class)
            .useDefaultResponseMessages(false)
            // メソッド毎の共通エラーレスポンスを定義
            .globalResponseMessage(RequestMethod.GET, getErrorResponses()); // (4)
            // 複数ある場合は、.globalResponseMessage()を追加する。
    }

    // (1)APIの基本情報を定義
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("APIタイトルを表示する") 
                .description("APIの説明を表示する") 
                .termsOfServiceUrl("利用規約URLを表示する")
                .contact(new Contact("名前", "https://example.com", "test@example.jp"))
                .license("APIのライセンス情報")
                .licenseUrl("APIのライセンスURL")
                .version("APIのバージョン") 
                .build();
    }

    // (2)対象とするRequestHandlerを定義
    private Predicate<String> paths() {
        return ant("/members/**");
        // 複数ある場合は、return or(ant("/foo/**"), ant("/bar/**")) のように記述する。
    }

    // (3) securitySchemesを定義
    private List<SecurityScheme> securityScheme() {
        return newArrayList(
                new OAuth(
                    "members_auth", 
                    asList(
                        new AuthorizationScope("write_members", "modify members in your account"),
                        new AuthorizationScope("read_members", "read your members")),
                    Arrays.<GrantType> asList(new ImplicitGrant(
                        new LoginEndpoint("http://members.swagger.io/api/oauth/dialog"), "tokenName"))),
                new ApiKey("api_key", "api_key", "header"));
    }

    // (4)-1 GETメソッドの共通エラーレスポンスを定義
    private List<ResponseMessage> getErrorResponses() {
        return newArrayList(
                createErrorResponseMessage(403, "ユーザまたはクライアントに、その操作をする権限が足りない。"),
                createErrorResponseMessage(404, "指定したリソースが見つからない。")
        );
    }

    // (4)-2 ResponseMessageを生成するためのメソッド
    private ResponseMessage createErrorResponseMessage(int code, String message) {
        return new ResponseMessageBuilder()
            .code(code)
            .message(message)
            .responseModel(new ModelRef("ErrorResponse"))
            .build();
    }
}

• restApi を見やすくするために apiInfo などの詳細な定義を切り出しましたが、細かい設定をしないなら restApi でまとめてもよいです。
• genericModelSubstitutes は、繰り返し同じ処理を書くことになるのでResponseMessage生成部分を createErrorResponseMessage としてメソッドを切り出しています。
• ResponseMessageBuilder の responseModel を設定する場合は、表示したいモデル定義クラスにリファレンス名を設定しておく必要があります。

共通部分の設定は、これで終了になります。

SwaggerUIでAPI仕様書を表示する

API仕様書生成用に簡単なAPIを作成し、ブラウザからAPI仕様書を確認します。

bootRun でアプリケーションを起動します。起動後、http://localhost:8080/swagger-ui.html にアクセスすると、以下のようなAPI仕様書が表示されます。

まとめ

今回は環境設定編として、ライブラリの追加と、仕様書を生成するためのDocketを定義し、ブラウザからAPI仕様書を確認しました。お分かりの通り、共通部分を設定しただけなので、仕様書としてはもうちょっと説明を加えるなどカスタマイズしたいところです。
ということで、次回はモデルやコントローラーにアノテーションを付加して細かい設定をしていきたいと思います。

おわりに

今年も一年ありがとうございました。私の拙いブログを見てくださったことに感謝です。
今年は事務職からエンジニアにジョブチェンジするという、なかなか濃い一年でした。これからも引き続き頑張っていきます。
そのうち、ジョブチェンジしたときに戸惑ったことや気付いたことなどをまとめたブログを書きたいなと思ってます。（ポエムカテゴリーで）
また来年も宜しくお願いしますm(_ _)m
by くにきち