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。在控制器级别使用@ApiResponses。

在控制器级别定义通用响应，而不是为每个方法重复它们：

@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 匹配方法返回类型，则不需要指定response 类型。因此，在提供的示例中，我们可以为每个控制器定义一次所有响应，以减少重复注释。

2。使用自定义注释

通过定义自定义注解在控制器之间共享重复注解：

/**
 * 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 获得。