spring - swagger结合一些重复的注释

Question

我在每个方法中使用.useDefaultResponseMessages(false)

@ApiResponses(value = {
        @ApiResponse(code = 200, message = "Success", response = Order.class),
        @ApiResponse(code = 401, message = "Unauthorized"),
        @ApiResponse(code = 403, message = "Forbidden"),
        @ApiResponse(code = 404, message = "Not Found"),
        @ApiResponse(code = 500, message = "Failure")})
public Order getOrder......

@ApiResponses(value = {
        @ApiResponse(code = 200, message = "Success", response = User.class),
        @ApiResponse(code = 401, message = "Unauthorized"),
        @ApiResponse(code = 403, message = "Forbidden"),
        @ApiResponse(code = 404, message = "Not Found"),
        @ApiResponse(code = 500, message = "Failure")})
public User getUser......

我可以合并一些重复的注释吗？(默认)

Answer 1

1。在 Controller 级别使用 @ApiResponses。

在 Controller 级别定义通用响应，而不是为每个方法重复它们:

@ApiResponses({
        @ApiResponse(code = 401, message = "Unauthorized"),
        @ApiResponse(code = 403, message = "Forbidden"),
        @ApiResponse(code = 404, message = "Not Found"),
        @ApiResponse(code = 500, message = "Failure")})
@Controller
public class UserOrderController {
    @ApiResponse(code = 200, message = "Success", response = Order.class)
    @GetMapping("/order")
    public Order getOrder() { /*......*/ }

    @ApiResponse(code = 200, message = "Success", response = User.class)
    @GetMapping("/user")
    public User getUser() { /*......*/ }
}

实际上，如果 @ApiResponse 与方法返回类型匹配，则不需要在 @ApiResponse 中指定 response 类型。因此，在提供的示例中，我们可以为每个 Controller 定义一次所有响应，以减少重复注释。

2。使用自定义注释

通过定义自定义注释在 Controller 之间共享重复注释:

/**
 * A convenient meta-annotation for Swagger API responses.
 */
@Target({ElementType.METHOD, ElementType.TYPE})
@Retention(RetentionPolicy.RUNTIME)
@ApiResponses({
        @ApiResponse(code = 200, message = "Success"),
        @ApiResponse(code = 401, message = "Unauthorized"),
        @ApiResponse(code = 403, message = "Forbidden"),
        @ApiResponse(code = 404, message = "Not Found"),
        @ApiResponse(code = 500, message = "Failure")})
@interface DefaultApiResponses {}

然后像这样使用它:

@DefaultApiResponses
@Controller
public class UserOrderController {
    @GetMapping("/order")
    public Order getOrder() { /*......*/ }

    @GetMapping("/user")
    public User getUser() { /*......*/ }
}

此答案中提供的源代码可在 Github 上找到。 .