swagger - @ApiResponse 注解在 Swagger 中的可重用性

Question

我正在使用 Swagger 注释来记录非 spring 上下文中的 API。我发现 400、401 和 404 的响应文档是可重复使用的。由于记录每个响应代码大约需要 8 行，如下所示。

    @Operation(
            summary = "getDetails",
            description = "someDescription",
            responses = {
                    @ApiResponse(
                            responseCode = "200",
                            description = "Found",
                            content = @Content(mediaType = "application/json",
                                    schema =  @Schema(
                                            name = "Response for success")
                            )
                    ),
                    @ApiResponse(
                            responseCode = "400",
                            description = "Validation failure on inputs.",
                            content = @Content(
                                    mediaType = "application/json",
                                    schema = @Schema(
                                            name = "Response For Bad Request")
                            )
                    ),
                    @ApiResponse(
                            responseCode = "404",
                            description = "Not found",
                            content = @Content(
                                    mediaType = "application/json",
                                    schema = @Schema(
                                            name = "Response For Not Found Request")
                            )

                    ),
                    @ApiResponse(
                            responseCode = "401",
                            description = "Unauthorized",
                            content = @Content(
                                    mediaType = "application/json",
                                    schema = @Schema(
                                            name = "Response For Unauthorized")
                            )
                    )
            }
    )

我打算防止每个可重用 API 响应的行膨胀。我更喜欢下面这样的东西

  @Operation(
            summary = "getDetails",
            description = "someDescription",
            responses = {
                   @ApiResponse(
                            responseCode = "200",
                            description = "Found",
                            content = @Content(mediaType = "application/json",
                                    schema =  @Schema(
                                            name = "Response for success")
                            )
                    ),
                    SomeStaticClass.getBadResponseDesc(),
                    SomeStaticClass.getUnauthorizedResponseDesc()
}

有什么办法可以在 java 8 中实现这一点吗？

Answer 1

是的，在 Docket 对象上使用 globalResponseMessage。参见 point 22在 springfox 文档中获取它们的使用示例。我使用这种方法从我的代码中删除了很多 @ApiResponse 注释。