关于响应
老的HTTP+JSON RPC接口，无论成功/失败，响应格式一般是固定的，例如：
1
2
3
4
5
6
7
8
| {
"code":"000",
"message":"成功",
"data":{
"productId":"123",
"productName":"产品名称"
}
}
|
REST风格接口中，一般是这样处理：
如果业务处理成功，HTTP STATUS返回2XX，BODY直接返回业务内容：
1
2
3
4
| {
"productId":"123",
"productName":"产品名称"
}
|
如果业务处理失败，HTTP STATUS返回4XX或5XX，这时才会展现报错信息：
1
2
3
4
| {
"code":"999",
"message":"失败原因"
}
|
业务成功和业务失败，会对外使用两套不同的模型。
Swagger中的展示
Swagger中默认只会展示业务处理成功时的模型：
Response Messages中的Response Model不会显示：
如果吹毛求疵的话，我们需要将业务失败时模型的内容展示出来，例如这样：
注解方式配置
使用注解方式，可以单独为一个API配置Response Model
1
2
3
4
5
6
| @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的类。
1
| @ApiResponses({@ApiResponse(code = 500, message = "服务器内部错误", response = ApiError.class)})
|
然后，在Swagger配置类的Docket上加入globalResponseMessage
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
| @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