Swagger2常用注解

网上收集整理，个人学习记录。

-------------------------------------------------------------------------------------------------------------------

本文说明：

1.版本：springfox-swagger2（2.4.0）springfox-swagger-ui （2.4.0） 
2.需要对swagger完成集成，如果没有集成的可以参考我的另一篇文章：Spring boot集成swagger2

 

 

 

常用注解介绍：

- @Api()用于类
表示标识这个类是swagger的资源 
- @ApiOperation()用于方法
表示一个http请求的操作 
- @ApiParam()用于方法，参数，字段说明
表示对参数的添加元数据（说明或是否必填等） 
- @ApiModel()用于类 
表示对类进行说明，用于参数用实体类接收 
- @ApiModelProperty()用于方法，字段 
表示对model属性的说明或者数据操作更改 
- @ApiIgnore()用于类，方法，方法参数 
表示这个方法或者类被忽略 
- @ApiImplicitParam() 用于方法 
表示单独的请求参数 
- @ApiImplicitParams() 用于方法，包含多个 @ApiImplicitParam
- @ApiResponses
用在请求的方法上，表示一组响应
- @ApiResponse
用在@ApiResponses中，一般用于表达一个错误的响应信息

 

 

 

 

常用注解使用示例：

@Api() 
用于类；表示标识这个类是swagger的资源 
tags–表示说明 
value–也是说明，可以使用tags替代 
但是tags如果有多个值，会生成多个list

例：

@Api(value="swaggerController",tags={"swaggerDemoController相关的api1","swaggerDemoController相关的api2"})
public class SwaggerDemoController {

}

 

 

 

@ApiOperation() 用于方法；表示一个http请求的操作 
value用于方法描述 
notes用于提示内容 
tags可以重新分组（视情况而用）

例：

@ApiOperation(value = "根据id查询学生信息", notes = "查询数据库中某个的学生信息")

 

 

@ApiOperation(value = "根据id查询学生信息", notes = "查询数据库中某个的学生信息",tags={"swaggerDemoController的getStudent1",
        "swaggerDemoController的getStudent2"})

 

 

 

@ApiParam() 用于方法，参数，字段说明；表示对参数的添加元数据（说明或是否必填等） 
name–参数名 
value–参数说明 
required–是否必填

例:

public Student getStudent(@PathVariable @ApiParam(name="id",value="学生id说明",required=true) int id) {
    logger.info("开始查询某个学生信息");
    return studentService.selectStudentById(id);
}

 

 

@ApiModel()用于类 ；表示对类进行说明，用于参数用实体类接收 
value–表示对象名 
description–描述 
都可省略 

 

@ApiModelProperty()用于方法，字段； 表示对model属性的说明或者数据操作更改 
value–字段说明 
name–重写属性名字 
dataType–重写属性类型 
required–是否必填 
example–举例说明 
hidden–隐藏

例:

@ApiModel(value = "user对象", description = "用户对象user")
public class User implements Serializable {
    private static final long serialVersionUID = 1L;
    private String userId;
    @ApiModelProperty(value = "用户名", name = "userName", example = "baidu1")
    private String userName;
    @ApiModelProperty(value = "状态", name = "state", required = true)
    private String state;
    @ApiModelProperty(hidden = true)
    private String extendColumn1;

}

 

 

@ApiIgnore()用于类或者方法上，可以不被swagger显示在页面上 

例：

@ApiIgnore()
public User getUser(@RequestBody @ApiParam(name = "用户对象", value = "传入json格式", required = false) User user) {
    logger.info("开始查询某个用户信息");
    user.setUserId("abc");
    return user;
}

如下图 getUser() 已经没有被显示了

 

 

@ApiImplicitParams() 用于方法，包含多个 @ApiImplicitParam

@ApiImplicitParam() 用于方法，表示单独的请求参数 
name–参数ming 
value–参数说明 
dataType–数据类型 
paramType–参数类型 
example–举例说明
例:

@ApiImplicitParams({
        @ApiImplicitParam(name = "name", value = "学生名", dataType = "String", paramType = "query", example =
                "baidu2"),
        @ApiImplicitParam(name = "id", value = "学生id", dataType = "String", paramType = "path")})
@RequestMapping(value = "/{id}", method = RequestMethod.GET)
public Student getStudent(@PathVariable @ApiParam(name = "id", value = "学生id说明", required = true) String id) {
    logger.info("开始查询某个学生信息");
    return studentService.selectStudentById(id);
}

 

 

 

@ApiResponses：用于请求的方法上，表示一组响应
@ApiResponse：用在@ApiResponses中，一般用于表达一个错误的响应信息
code：数字，例如400
message：信息，例如"请求参数没填好"

例:

@ApiResponses({
        @ApiResponse(code = 400, message = "请求参数没填好"),
        @ApiResponse(code = 404, message = "请求路径没有或页面跳转路径不对")
})

 

 

 

注意：code值必须是http 返回code值，如果不是会报错

例：

@ApiResponses({
        @ApiResponse(code = 12345, message = "上山打老虎"),
        @ApiResponse(code = 400, message = "请求参数没填好"),
        @ApiResponse(code = 404, message = "请求路径没有或页面跳转路径不对")
})

 

 

 

 

 

 

 

 

 

参考资料：

https://blog.csdn.net/u014231523/article/details/76522486#commentBox

https://blog.csdn.net/xiaojin21cen/article/details/78654652