SpringFoxについて

• ・Spring Bootで作られたAPI向けのライブラリ。
• ・導入すると、サーバーがSwagger Specをjsonで返してくれるようになる。
• ・ソースコードにコメントを書く感覚でSwaggerを利用できるようになるので便利。

公式github

この記事では、SpringFoxにおけるリクエスト・レスポンス説明の共通化をいくつか紹介します。

1.group単位で共通のパラメータを設定する

springfoxはURLPathで区切られたgroupという単位に分けることができます。
このgroup単位で共通のリクエスト・レスポンスパラメータを設定することができます。

@Bean
  public Docket petApi() {
    return new Docket(DocumentationType.SWAGGER_2)
	    .groupName("sample-api")    
        .select()
        .pathMapping("/api/*")
        .build()
        .apiInfo(apiInfo())
		.globalResponseMessage(RequestMethod.GET,
            newArrayList(new ResponseMessageBuilder()
                .code(500)
                .message("500 message")
                .responseModel(new ModelRef("Error"))
                .build()))
		.globalOperationParameters(
            newArrayList(new ParameterBuilder()
                .name("someGlobalParameter")
                .description("Description of someGlobalParameter")
                .modelRef(new ModelRef("string"))
                .parameterType("query")
                .required(true)
                .build()));

globalResponseMessageが共通のレスポンスパラメータ説明の付与、

globalOperationParametersが、共通のリクエストパラメータ説明の付与です。

URLPathで区切るので、例えば「https://hoge.jp/api/～以下は、すべて共通のパラメータを持ちたい」といった時に使います。

参考：公式ドキュメント

2.継承元のClassに設定する

@ApiResponses(value = {
    @ApiResponse(code = 400, message = "ValidationError", response = ErrorResponse.class),
    @ApiResponse(code = 403, message = "Forbidden", response = ErrorResponse.class)
})
public class BaseController { ～ }

public class ApiController extends BaseController { ～ }

この例のように書くと継承先のClassのAPI全てに@ApiResponsesが適応されます。Class単位で共通のレスポンスを設定したい場合に使えます。

SpringFoxはいろいろな書き方のできるライブラリなので、「こんなことできないかな？」と思ったら、一度公式ドキュメントを探ってみるといいかもしれません。