最近仕事でSpringBootを使う機会ができたのでSpringFoxを使ってみました。　　 REST APIを作ったとき殆どの場合でそのAPIのドキュメントを用意する必要があると思います。大体の場合はSwaggerを使うと思うのですが（Railsのときはそうでした）これを手書きするのはかなり手間です。
特にエンジニアにとってドキュメントを書く作業は退屈なはずなので自動で作って欲しいですよね。Railsでは難しかったのですが、偶然にもJavaは静的型付けの言語なので（最高ですね）型からいい感じにドキュメントを作れそうです。

SpringFoxを使ってみる

build.gradleで以下の依存関係を追加しましょう。残念ながらstarterはないようです。

implementation('io.springfox:springfox-swagger2:+')
implementation('io.springfox:springfox-swagger-ui:+')

あとはちょっと設定を追加すれば出来上がりです。

@SpringBootApplication
@EnableSwagger2 // <- これと
public class MyApplication {

    public static void main(String[] args) {
        SpringApplication.run(MyApplication.class, args);
    }

    // このBean
    @Bean
    public Docket document() {
        return new Docket(DocumentationType.SWAGGER_2).select().paths(PathSelectors.any()).build();
    }
}

/swagger-ui.htmlにアクセスすればSwaggerの画面が見れるはずです。このパスを変更する方法は調べましたが、提供されてなさそうです。

情報を増やす

APIのパラメータとレスポンスについては自動的に作ってくれますが、APIの説明がないので付け加えたいですね。
handler methodにアノテーションを書くことで説明を追加することができます。

@ApiOperation("ここにAPIの説明")
@ApiResponses({
        @ApiResponse(code = 400, response = ErrorDetails.class, message = "エラー時のレスポンス")
})
@GetMapping("/hoge")
public HogeResponse hoge(@RequestParam(value = "page", defaultValue = "1") int page) {
...
}

手軽に使えるのでAPIを作る場合はとりあえず入れておけば良いと思いました。