swagger2的常用注解

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

 

 

 

转载于:https://my.oschina.net/zhaolin/blog/3050505