Spring Bootで構築したAPIのDocumentをSwagger-UIで自動生成する

こんな人向け

API適当に作ったけど、メンバーに共有するの面倒くさいし自分でもあれこれ探すのめんどい。
とりあえずサクッと一覧で見たいんじゃ

前提

1. Spring Bootの2系を使っている

やること

1. 依存関係にswaggerを追加する
2. config設定（やらなくてもいい）

依存関係にswaggerを追加する

一行追加するだけ

implementation 'io.springfox:springfox-boot-starter:3.0.0'

2021/12/25現在の最新バージョンは3.0.0
最新バージョンは下記参照
https://search.maven.org/artifact/io.springfox/springfox-boot-starter

config設定（やらなくてもいい）

よくわからん人は下のコードをコピってスキャン対象に含める。

import java.time.LocalDate;
import java.time.OffsetDateTime;
import java.util.HashSet;
import java.util.List;
import java.util.Set;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.http.ResponseEntity;
import org.springframework.http.converter.HttpMessageConverter;
import org.springframework.http.converter.json.MappingJackson2HttpMessageConverter;
import org.springframework.web.servlet.config.annotation.EnableWebMvc;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;

import com.fasterxml.jackson.databind.ObjectMapper;
import com.fasterxml.jackson.databind.PropertyNamingStrategies;

import springfox.documentation.builders.PathSelectors;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;

@Configuration
public class SwaggerConfig implements WebMvcConfigurer {

    @Bean
    public Docket document() {
    	Set<String> protocols = new HashSet<>();
    	protocols.add("http");
    	protocols.add("https");
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                    // ① 指定したパス以下のAPIのみを対象としたい場合記述する。指定しないとSpringのデフォルトのエラーとかまで出力する
                    .paths(PathSelectors.regex("^\\/api.*"))
                    .build()

                // ② directModelSubstituteを指定するとJava8の日付がちゃんと文字列で出る
                // 指定しないと保持するメンバ変数全部返す
                .directModelSubstitute(OffsetDateTime.class, java.util.Date.class)
                .directModelSubstitute(LocalDate.class, java.sql.Date.class)

                // ③ useDefaultResponseMessagesをtrueにすると200,201,400などのデフォルトのステータスコードを各APIのレスポンスに出力する
                .useDefaultResponseMessages(false)

                // ④ 利用可能なprotocolを指定できる
                .protocols(protocols)

                // ⑤ ResponseEntity<> で指定している部分がある場合は下記を指定することでResponseEntityのメンバ変数を返却しなくてすむ
                .genericModelSubstitutes(ResponseEntity.class);
    }
    
    @Override
    public void extendMessageConverters(List<HttpMessageConverter<?>> converters) {
        ObjectMapper objectMapper = null;
        for (HttpMessageConverter<?> converter : converters) {
            if (converter instanceof MappingJackson2HttpMessageConverter ) {
                MappingJackson2HttpMessageConverter jacksonConverter =
                        ((MappingJackson2HttpMessageConverter) converter);

                if (objectMapper == null) {
                    objectMapper = jacksonConverter.getObjectMapper();
                    //CamelCaseをSnakeCaseに変換する
                    objectMapper.setPropertyNamingStrategy(PropertyNamingStrategies.SNAKE_CASE);
                } else {
                    jacksonConverter.setObjectMapper(objectMapper);

                }
            }
        }
    }
}

結果

アクセス：http://localhost:8080/swagger-ui/index.html

こんな感じの一覧が表示される

それぞれを展開するとこんな感じ

参考

https://qiita.com/mitsuya/items/16b0284372b3f8e340af
https://github.com/springfox/springfox/issues/2837