Springfox 3.0で共通レスポンス(globalResponses)を設定する

Springfox 3.0.0

Springfoxのバージョンが3.0.0となり、バージョン2.xから書式がいろいろ変わっています。

これまでの2.x系ではレスポンスの応答内容を一括指定するグローバルレスポンスを設定するときには ”Docket::globalResponseMessage” を使用していました。
この ”Docket::globalResponseMessage” は3.0ではDeprecatedとなり、”Docket::globalResponses”の使用が推奨されています。
またメソッドの変更に伴い引数の設定も ”ResponseMessageBuilder” から ”ResponseBuilder” に変更されました。

バージョン3.0のガイドもまだ少なく（実質、公式のSpringfox Reference Documentation くらいしかない）、この公式ドキュメントも分かる人には分かるという感じなので、一例として2.xと3.0の違いを書いておきます。

globalResponses

2.xのglobalResponseMessageはCodeがintだったり、モデルクラスが直に指定できたりなんとなく直感的だったのですが、3.0では少し遠ざかったように感じます。

まずはglobalResponsesの引数のResponseクラスをResponseBuilderで作成します。
2.xではResponseMessageBuilderを利用していた部分です。

private List<Response> errorResponse = new ArrayList<>() {
        {
            add(new ResponseBuilder()
                .code("401")
                .description("Unauthorized")
                .build());
            add(new ResponseBuilder()
                .code("500")
                .description("Bad Request")
                .representation(MediaType.APPLICATION_JSON)
                    .apply(r ->
                        r.model(m ->
                            m.referenceModel(ref ->
                                ref.key(k ->
                                    k.qualifiedModelName(q ->
                                        q.namespace(CustomErrorResponse.class.getPackageName())
                                            .name(CustomErrorResponse.class.getSimpleName()))))))
                .build());
        }
    };

ボディに付与するJsonのクラス指定が大変深くなっています。
このフォーマットを公式ドキュメントにも書いてあるのですが、深すぎて意味が分からずJavadocを一つ一つ追うはめになりました。

そしてこのResponseクラスをDocketに設定していきます。

@Autowired
private TypeResolver typeResolver;

@Bean
public Docket api() {
  return new Docket(DocumentationType.SWAGGER_2)
            .select()
              .apis(RequestHandlerSelectors.basePackage("xxxxxx"))
            .build()
            .useDefaultResponseMessages(false)
            .additionalModels(typeResolver.resolve(CustomErrorResponse.class))
            .globalResponses(HttpMethod.POST, errorResponse)
            .globalResponses(HttpMethod.PUT, errorResponse);
}

additionalModelsはExceptionに用意していたCustomErrorResponse.classがSpringfoxでモデルとして読み込まれなかったため設定しています。設定がないとUIのExample Valueが空欄となってしまいます。
コントローラー等に設定しているクラスならば自動的に読み込まれるはずなので、当設定は不要です。

これでUI（/swagger-ui/index.htm）にアクセスすると、応答コードとJsonフォーマットが例として表示されるようになります。
なおサクセスコード（以下の例では204）は自動的に設定されます。