SpringFoxでのSwaggerのリクエスト・レスポンス説明の共通化 | GROUP DEV BLOG

2020.03.31

未分類

SpringFoxでのSwaggerのリクエスト・レスポンス説明の共通化

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()));

@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 { ～ }