swagger2常用注解介绍说明

3人阅读 评论(0) 收藏 举报
分类:

说明: 
1.这里使用的版本:springfox-swagger2(2.4)springfox-swagger-ui (2.4) 
2.这里是说明常用注解的含义和基本用法(也就是说已经对swagger进行集成完成) 
没有集成的请参见 
SpringBoot集成springfox-swagger2构建restful API 
SpringMVC集成springfox-swagger2构建restful API 
官网WIKI 
常用注解: 
@Api()用于类; 
表示标识这个类是swagger的资源 
@ApiOperation()用于方法; 
表示一个http请求的操作 
@ApiParam()用于方法,参数,字段说明; 
表示对参数的添加元数据(说明或是否必填等) 
@ApiModel()用于类 
表示对类进行说明,用于参数用实体类接收 
@ApiModelProperty()用于方法,字段 
表示对model属性的说明或者数据操作更改 
@ApiIgnore()用于类,方法,方法参数 
表示这个方法或者类被忽略 
@ApiImplicitParam() 用于方法 
表示单独的请求参数 
@ApiImplicitParams() 用于方法,包含多个 @ApiImplicitParam

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

@Api(value="用户controller",tags={"用户操作接口"})
@RestController
public class UserController {

}
  • 1
  • 2
  • 3
  • 4
  • 5

效果图: 
这里写图片描述

@ApiOperation() 用于方法;表示一个http请求的操作 
value用于方法描述 
notes用于提示内容 
tags可以重新分组(视情况而用) 
@ApiParam() 用于方法,参数,字段说明;表示对参数的添加元数据(说明或是否必填等) 
name–参数名 
value–参数说明 
required–是否必填

@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;
  }
}
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
  • 12

效果图: 
这里写图片描述

@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;
     @ApiModelProperty(value="用户名",name="username",example="xingguo")
     private String username;
     @ApiModelProperty(value="状态",name="state",required=true)
      private Integer state;
      private String password;
      private String nickName;
      private Integer isDeleted;

      @ApiModelProperty(value="id数组",hidden=true)
      private String[] ids;
      private List<String> idList;
     //省略get/set
}
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
  • 12
  • 13
  • 14
  • 15
  • 16
  @ApiOperation("更改用户信息")
  @PostMapping("/updateUserInfo")
  public int updateUserInfo(@RequestBody @ApiParam(name="用户对象",value="传入json格式",required=true) User user){

     int num = userService.updateUserInfo(user);
     return num;
  }
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7

效果图: 
这里写图片描述

这里写图片描述

@ApiIgnore()用于类或者方法上,可以不被swagger显示在页面上 
比较简单, 这里不做举例

@ApiImplicitParam() 用于方法 
表示单独的请求参数 
@ApiImplicitParams() 用于方法,包含多个 @ApiImplicitParam 
name–参数ming 
value–参数说明 
dataType–数据类型 
paramType–参数类型 
example–举例说明

  @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(){

  }
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9

效果图: 
这里写图片描述

查看评论

swagger2 注解说明

swagger2 注解整体说明 @Api:用在请求的类上,表示对类的说明 tags="说明该类的作用,可以在UI界面上看到的注解" value="该参数没什么意义,在UI界面上也...
  • xiaojin21cen
  • xiaojin21cen
  • 2017-11-28 14:23:02
  • 3380

swagger2常用注解说明

@Api()表示标识这个类是swagger的资源 @ApiOperation()表示一个http请求的操作 @ApiParam()表示对参数的添加元数据 @ApiModel()表示对类进行说明,用...
  • u014231523
  • u014231523
  • 2017-08-01 14:00:38
  • 21782

swagger2注解详细说明

@Api:用在请求的类上,表示对类的说明 tags="说明该类的作用,可以在UI界面上看到的注解" value="该参数没什么意义,在UI界面上也看到,所以不需要配置" @ApiOp...
  • qq_28009065
  • qq_28009065
  • 2018-01-19 10:50:52
  • 667

SpringMVC注解配置Swagger2步骤及相关知识点

Swagger2的功能不多说了,百度一下随处可见,配置步骤也十分简单,但一些点百度到的很多都不太详细,个人进行了一些补充 1、pom.xml添加swagger2依赖(个人一般直接到http://se...
  • z28126308
  • z28126308
  • 2017-05-03 18:56:34
  • 3430

Springfox Swagger2(二):常用注解

@ApiIgnore():用于类或者方法上,可以不被swagger显示在页面上 @Api():用于类表示标识这个类是swagger的资源     tags–表示说明 但是tags如果有多个值,会生成多...
  • lsxf_xin
  • lsxf_xin
  • 2018-03-15 14:34:30
  • 19188

springboot + swagger一些注解总结

swagger用于定义API文档。 好处: 前后端分离开发API文档非常明确测试的时候不需要再使用URL输入浏览器的方式来访问Controller传统的输入URL的测试方式对于post请求...
  • q1512451239
  • q1512451239
  • 2016-12-12 14:55:43
  • 1237

springboot 一些常用的注解介绍

springboot 一些常用的注解介绍Author QiuRiMangCao 秋日芒草@SpringBootApplication(scanBasePackages = {“com.qiu”}, e...
  • qq_26334813
  • qq_26334813
  • 2017-10-23 17:06:51
  • 475

swa.gger常用注解说明

常用到的注解有: ApiApiModelApiModelPropertyApiOperationApiParamApiResponseApiResponsesResponseHeader api...
  • lmjy102
  • lmjy102
  • 2017-07-05 17:13:03
  • 1401

springboot+swagger2说明

swagger用于定义API文档。 优势: 前后端分离开发API文档非常明确测试的时候不需要再使用URL输入浏览器的方式来访问Controller传统的输入URL的测试方式对于post请求的传参比...
  • fanpeng1100
  • fanpeng1100
  • 2017-01-04 10:09:18
  • 7400

使用springfox+swagger2书写API文档

主要介绍springfox自动生成API文档的配置与使用并结合swagger2展示书写的API,着重介绍springMVC中如何使用配置、使用springfox。...
  • u012476983
  • u012476983
  • 2017-01-05 10:37:31
  • 29109
    个人资料
    等级:
    访问量: 486
    积分: 321
    排名: 25万+
    文章存档