Swagger配置全局Response Model

关于响应

老的HTTP+JSON RPC接口，无论成功/失败，响应格式一般是固定的，例如：

{
  "code":"000",
  "message":"成功",
  "data":{
    "productId":"123",
    "productName":"产品名称"
  }
}

REST风格接口中，一般是这样处理：
如果业务处理成功，HTTP STATUS返回2XX，BODY直接返回业务内容：

{
  "productId":"123",
  "productName":"产品名称"
}

如果业务处理失败，HTTP STATUS返回4XX或5XX，这时才会展现报错信息：

{
  "code":"999",
  "message":"失败原因"
}

业务成功和业务失败，会对外使用两套不同的模型。

Swagger中的展示

Swagger中默认只会展示业务处理成功时的模型：

Response Messages中的Response Model不会显示：

如果吹毛求疵的话，我们需要将业务失败时模型的内容展示出来，例如这样：

注解方式配置

使用注解方式，可以单独为一个API配置Response Model

@ApiResponses({
        @ApiResponse(code = 400, message = "业务逻辑异常", response = ApiError.class),
        @ApiResponse(code = 407, message = "XX异常", response = ApiError.class),
        ... ...
        @ApiResponse(code = 500, message = "服务器内部错误", response = ApiError.class)
})

这样做的缺点显而易见，每个Controller上都会有一大堆的、重复的@ApiResponses注解，以至于把正常的业务代码淹没。

全局配置

通过Swagger的全局配置，可以自定义默认的Response Model。

首先，在任何一个Controller上，添加至少一个@ApiResponses注解，标明response的类。

@ApiResponses({@ApiResponse(code = 500, message = "服务器内部错误", response = ApiError.class)})

然后，在Swagger配置类的Docket上加入globalResponseMessage

@Bean
public Docket userApi() {
    List<ResponseMessage> responseMessageList = new ArrayList<>();
    responseMessageList.add(new ResponseMessageBuilder().code(404).message("找不到资源").responseModel(new ModelRef("ApiError")).build());
    responseMessageList.add(new ResponseMessageBuilder().code(409).message("业务逻辑异常").responseModel(new ModelRef("ApiError")).build());
    responseMessageList.add(new ResponseMessageBuilder().code(422).message("参数校验异常").responseModel(new ModelRef("ApiError")).build());
    responseMessageList.add(new ResponseMessageBuilder().code(500).message("服务器内部错误").responseModel(new ModelRef("ApiError")).build());
    responseMessageList.add(new ResponseMessageBuilder().code(503).message("Hystrix异常").responseModel(new ModelRef("ApiError")).build());

    return new Docket(DocumentationType.SWAGGER_2)

            .globalResponseMessage(RequestMethod.GET, responseMessageList)
            .globalResponseMessage(RequestMethod.POST, responseMessageList)
            .globalResponseMessage(RequestMethod.PUT, responseMessageList)
            .globalResponseMessage(RequestMethod.DELETE, responseMessageList)

            .build()
            .apiInfo(apiInfo());

}

请注意第一条不能省略，new ModelRef("ApiError")，会查询之前定义@ApiResponse的response中指定的class