swagger 结合一些重复的注解 [英] swagger combine some repeating annotations

问题描述

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

I use .useDefaultResponseMessages(false) and in each method

@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......

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

Can I combine some repeating annotations?(default)

推荐答案

1.在控制器级别使用 @ApiResponses.

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

1. Use @ApiResponses at controller level.

Define common responses at the controller level instead of repeating them for each method:

@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 类型.因此，在提供的示例中，我们可以为每个控制器定义一次所有响应，以减少重复注释.

And actually, it's not required to specify response type in @ApiResponse if it matches method return type. So, in the provided example, we can define all responses once per controller in order to reduce repeating annotations.

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

Share the repeating annotations between controllers by defining a custom annotation:

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

The source code presented in this answer is available over on Github.

这篇关于swagger 结合一些重复的注解的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！