【Springfox】HTTPメソッド・レスポンスステータスコードごとにデフォルトの説明を設定する

8748 ワード
Springfox spring-boot swagger OpenAPI Kotlin Kotlin テキストリンク

TL;DR

  • Docketに対し、HTTPメソッドごとにglobalResponsesを設定することで、デフォルトの説明を上書きできる

やること

Springfoxは、HTTPメソッドごとに頻出するレスポンスステータスコードについてデフォルトの説明を設定します。
例えば、GETのエンドポイントでは、以下のように200, 401, 403, 404への説明が入った状態になります。

これらの説明は@ApiResponses/@ApiResponseアノテーションによってエンドポイントごとに上書きすることもできますが、全エンドポイントにこれらのアノテーションを付けるのは面倒です。
そこで、これらを上書きする設定をします。

コンフィグは以下を元に説明します。
Springfoxのバージョンは3.0.0です。

import org.springframework.context.annotation.Bean
import org.springframework.context.annotation.Configuration
import springfox.documentation.builders.PathSelectors
import springfox.documentation.builders.RequestHandlerSelectors
import springfox.documentation.spi.DocumentationType
import springfox.documentation.spring.web.plugins.Docket

@Configuration
class SpringFoxConfig {
    @Bean
    fun api(): Docket = Docket(DocumentationType.OAS_30)
        // 対象とするAPI、ここでは全パス指定
        .select()
        .apis(RequestHandlerSelectors.any())
        .paths(PathSelectors.any())
        .build()
}

その他前提となるコード

コントローラー

コントローラーは以下の通りです。
余計な設定も入っていますが、説明の本題には関係しないので無視してください。

import com.wrongwrong.openapidemo.enumable.SampleEnum
import com.wrongwrong.openapidemo.form.SampleForm
import com.wrongwrong.openapidemo.view.SampleView
import io.swagger.annotations.ApiParam
import org.springframework.web.bind.annotation.*

@RestController
class DemoController {
    @GetMapping("/sample/get")
    fun getSample(@RequestParam @ApiParam(allowableValues = "Hoge,Fuga") enum: SampleEnum): SampleView {
        return SampleView(enum)
    }

    @PostMapping("/sample/post")
    fun postSample(@RequestBody form: SampleForm) {}
}

やり方

HTTPメソッドごとにglobalResponsesを設定することで、デフォルトの説明を上書きできます。
以下の例では、GETの301と500にそれぞれ説明を設定しています。

import org.springframework.context.annotation.Bean
import org.springframework.context.annotation.Configuration
import org.springframework.http.HttpMethod
import springfox.documentation.builders.PathSelectors
import springfox.documentation.builders.RequestHandlerSelectors
import springfox.documentation.builders.ResponseBuilder
import springfox.documentation.spi.DocumentationType
import springfox.documentation.spring.web.plugins.Docket

@Configuration
class SpringFoxConfig {
    @Bean
    fun api(): Docket = Docket(DocumentationType.OAS_30)
        .globalResponses(
            HttpMethod.GET,
            listOf(
                ResponseBuilder()
                    .code("301")
                    .description("認証切れに伴うログイン画面へのリダイレクト")
                    .build(),
                ResponseBuilder()
                    .code("500")
                    .description("不正な操作によるシステムエラー、またはサーバーサイドの実装の問題によるエラー")
                    .build()
            )
        )
        // 対象とするAPI、ここでは全パス指定
        .select()
        .apis(RequestHandlerSelectors.any())
        .paths(PathSelectors.any())
        .build()
}

この設定によって以下のように表示されるようになります。
デフォルトで入っていた400系の説明は表示されなくなります。

補足

200に関しては上書きの仕方が分からず、一旦自分に取って需要も無かったので調査していません。