Spring bootで作ったWeb APIのドキュメントを自動で生成するライブラリ「Spring Fox」

こんにちは!ぐち(@bloguchi)です。

前回ご紹介したSpring bootで作るRESTfulなAPIのドキュメントを自動で生成してくれる便利なライブラリをご紹介します。

前回の記事はこちらからどうぞ。

Swagger

Web APIのドキュメントとブラウザからリクエストを実行できるようなページを生成してくれるライブラリがあります。Swaggerというものですが、それをSpringと合わせて使えるようにしたのがSpring Fox(と認識しています。笑)です。

Swaggerに関しては公式サイトを見てください。

Spring Foxのサイトはこちらです。

プロジェクトに導入

では、早速プロジェクトに導入しましょう。前回チュートリアルで作成したプロジェクトに追加していきましょう。

まずはbuild.gradleに追加します。dependenciesに下記のように追加してください。

dependencies {
    compile('org.springframework.boot:spring-boot-starter-web')
    testCompile('org.springframework.boot:spring-boot-starter-test')

    // Spring Fox
    compile 'io.springfox:springfox-swagger2:2.2.2'
    compile 'io.springfox:springfox-swagger-ui:2.2.2'
    compile "com.google.guava:guava:17.0"
}

6行目から8行目に追加した3行がSpring Foxを使うために必要なものです。

続いてSpring Foxを使えるようにするための設定クラスを追加します。パッケージを右クリックしてAppConfig.javaを追加してください。

package com.example.hello;

import com.google.common.base.Predicate;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

import static com.google.common.base.Predicates.*;


@Configuration
@EnableSwagger2  // Springfoxを使うために必要なアノテーション
public class AppConfig {

    @Bean
    public Docket document() {
        return new Docket(DocumentationType.SWAGGER_2)
                .select().paths(paths()).build().apiInfo(apiInfo());
    }


    private Predicate<String> paths() {
        return or(containsPattern("/*")); // エントリポイントを指定
    }

    private ApiInfo apiInfo() {
        ApiInfo apiInfo = new ApiInfo("Greeting API", "This is Sample for Spring Fox.",
                "0.0.1", "", "", "", "");
        return apiInfo;
    }
}

これで導入は完了です。

実行

続いて実行してみましょう。IntelliJのTerminalを起動していつも通り下記のコマンドでOKです。

$ ./gradlew bootrun

前回までのチュートリアルであれば、表示するURLはhttp://localhost:8080/greetingでしたが、今回は下記のURLをブラウザで表示してみましょう。

http://localhost:8080/swagger-ui.html

上記のような画面が表示されているかと思います。

greeting-controllerという部分をクリックすることでRESTfulなエンドポイントが一覧で表示されるはずです。

続いてGETをクリックして開いてみましょう。パラメータやらレスポンスの種類などが表示されていますよね。いわゆるAPI仕様書が表示されているのです。すごく簡単ですよね。

では、早速Try it out!をクリックしてこのAPIを実行してみてください。前回のチュートリアルで確認した結果がResponse Bodyに表示されていれば成功です。Parametersに値を入れて実行してみても前回と同じ結果になっていますよね?

リクエストメソッドを制限する

ここまでの手順でAPIの仕様書とリクエストを実行できることがわかりましたが、GETPSOTなど全てのリクエストメソッドが表示されていますよね?特定のリクエストメソッドに制限したい場合(というか製品としては当然そうですよね?笑)は、Javaのメソッドに宣言しているアノテーションを下記のようにするだけでSpring Foxのドキュメントも変更されます。

@GetMapping("/greeting")
public Greeting greeting(@RequestParam(value="name", defaultValue="World") String name) {
    return new Greeting(counter.incrementAndGet(),
            String.format(template, name));
}

上記の例であればGETメソッドのみリクエスト許可を行うようになります。これで再度実行してみてください。Spring Foxで生成されたドキュメントも下記のように変更されます。

まとめ

ドキュメントが整備されておらず、ソースコードと乖離がある状態ってよくあると思うんですが、今回ご紹介したようなライブラリを使うことで、API仕様書とソースコードの乖離をなくすことができますし、メンテにも手間がかかりません。それに、実行結果を確認することもできるようになります。

こういうものを上手く活用して本来時間をかけるべき部分にじっくりと時間をかけて良い開発ができればいいですね!

では今回はこの辺で。