2019独角兽企业重金招聘Python工程师标准>>> 
一.
1.关于接口请求类：
@Api(value = "xxx接口",description = "xx接口",tags="xx接口组")
用在controller类上，标识整个类。 tags是分组。
接口请求方法：
@ApiOperation(value = "取消订单")
2.关于方法中请求参数的注解：
如果是一个类对象的话， 该类可以被自动注释。
如果是多个参数可以在方法上加
@ApiOperation("查询测试")
@GetMapping("select")
//@ApiImplicitParam(name="name",value="用户名",dataType="String", paramType = "query")
@ApiImplicitParams({
@ApiImplicitParam(name="name",value="用户名",dataType="string", paramType = "query",example="xingguo"),
@ApiImplicitParam(name="id",value="用户id",dataType="long", paramType = "query")})
public void select(){
}
也可以在参数前
@Api(value="用户controller",tags={"用户操作接口"})
@RestController
public class UserController {
@ApiOperation(value="获取用户信息",tags={"获取用户信息copy"},notes="注意问题点")
@GetMapping("/getUserInfo")
public User getUserInfo(@ApiParam(name="id",value="用户id",required=true) Long id,@ApiParam(name="username",value="用户名") String username) {
// userService可忽略，是业务逻辑
User user = userService.getUserInfo();
return user;
}
}3.model类的注解
@ApiModel("订单请求参数”)
public class CyOrder implements Serializable{
private static final long serialVersionUID = 1L;
@ApiModelProperty(value = "门店id")
private String storeId;
@ApiModel 用于说明类
@ApiModelProperty(value = "结束时间戳 10位",required = true) 用于说明属性
二.关于返回的说明
传统的返回数据格式多数是这样：
{
"code":"000",
"message":"成功",
"data":{
"productId":"123",
"productName":"产品名称"
}
}@ApiResponses({
@ApiResponse(code = 400, message = "业务逻辑异常", response = ApiError.class),
@ApiResponse(code = 407, message = "XX异常", response = ApiError.class),
... ...
@ApiResponse(code = 500, message = "服务器内部错误", response = ApiError.class)
})
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 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