一.
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={"用户操作接口"})@RestControllerpublic 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
@Beanpublic Docket userApi() { ListresponseMessageList = 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