网上收集整理,个人学习记录。
-------------------------------------------------------------------------------------------------------------------
本文说明:
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