最新公告
  • 欢迎您光临编程知识分享网 加入我们
  • swagger2.4注解大全

    1、与模型相关的注解,用在bean上面
    @ApiModel:用在bean上,对模型类做注释;
    @ApiModelProperty:用在属性上,对属性做注释

    2、与接口相关的注解
    @Api:用在controller上,对controller进行注释;
    @ApiOperation:用在API方法上,对该API做注释,说明API的作用;
    @ApiImplicitParams:用来包含API的一组参数注解,可以简单的理解为参数注解的集合声明;
    @ApiImplicitParam:用在@ApiImplicitParams注解中,也可以单独使用,说明一个请求参数的各个方面,该注解包含的常用选项有:
    paramType:参数所放置的地方,包含query、header、path、body以及form,最常用的是前四个。
    name:参数名;
    dataType:参数类型,可以是基础数据类型,也可以是一个class;
    required:参数是否必须传;
    value:参数的注释,说明参数的意义;
    defaultValue:参数的默认值;

    @ApiResponses:通常用来包含接口的一组响应注解,可以简单的理解为响应注解的集合声明;
    @ApiResponse:用在@ApiResponses中,一般用于表达一个响应信息
    code:即httpCode,例如400
    message:信息,例如”操作成功”
    response = UserVo.class 这里UserVo是一个配置了@ApiModel注解的对像,该是对像属性已配置 @ApiModelProperty,swagger可以通过这些配置,生 成接口返回值

    注意事项:
    为了在swagger-ui上看到输出,至少需要两个注解:@Api和@ApiOperation
    即使只有一个@ApiResponse,也需要使用@ApiResponses包住

    对于@ApiImplicitParam的paramType:query、form域中的值需要使用@RequestParam获取, header域中的值需要使用@RequestHeader来获取,path域中的值需要使用@PathVariable来获取,body域中的值使用@RequestBody来获取,否则可能出错;而且如果paramType是body,name就不能是body,否则有问题,与官方文档中的“If paramType is “body”, the name should be “body”不符。

    常用注解:

    @Api()用于类;
    表示标识这个类是swagger的资源
    @ApiOperation()用于方法;
    表示一个http请求的操作
    @ApiParam()用于方法,参数,字段说明;
    表示对参数的添加元数据(说明或是否必填等)
    @ApiModel()用于类
    表示对类进行说明,用于参数用实体类接收
    @ApiModelProperty()用于方法,字段
    表示对model属性的说明或者数据操作更改
    @ApiIgnore()用于类,方法,方法参数
    表示这个方法或者类被忽略
    @ApiImplicitParam() 用于方法
    表示单独的请求参数
    @ApiImplicitParams() 用于方法,包含多个 @ApiImplicitParam
    具体使用举例说明:
    @Api()
    用于类;表示标识这个类是swagger的资源
    tags–表示说明
    value–也是说明,可以使用tags替代
    但是tags如果有多个值,会生成多个list

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

    @ApiModel()用于类 ;表示对类进行说明,用于参数用实体类接收
    value–表示对象名
    description–描述
    都可省略
    @ApiModelProperty()用于方法,字段; 表示对model属性的说明或者数据操作更改
    value–字段说明
    name–重写属性名字
    dataType–重写属性类型
    required–是否必填
    example–举例说明
    hidden–隐藏

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

    @ApiImplicitParam() 用于方法
    表示单独的请求参数
    @ApiImplicitParams() 用于方法,包含多个 @ApiImplicitParam
    name–参数ming
    value–参数说明
    dataType–数据类型
    paramType–参数类型
    example–举例说明
    ————————————————
    版权声明:本文为CSDN博主「XQ@Y」的原创文章,遵循CC 4.0 BY-SA版权协议,转载请附上原文出处链接及本声明。
    原文链接:https://blog.csdn.net/qq_28190397/article/details/106213646

     

    1.这里使用的版本:springfox-swagger2(2.4)springfox-swagger-ui (2.4)
    2.这里是说明常用注解的含义和基本用法(也就是说已经对swagger进行集成完成)

    官网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 { }
    效果图:

    @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; } }
    效果图:

    @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 }
    @ApiOperation(“更改用户信息”)
    @PostMapping(“/updateUserInfo”)
    public int updateUserInfo(@RequestBody @ApiParam(name=”用户对象”,value=”传入json格式”,required=true) User user){ int num = userService.updateUserInfo(user); return num; }
    效果图:

     

    @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(){ }
    效果图:

     

     

     

     

     

     

     

     

    @Api 标识一个java类型是文档类,用controller类的类名上

    @ApiModel 表示一个实体类/模型文档,用在类名上;

    @ApiModelProperty 作用在属性上,添加属性描述;

    @ApiOperation 作用在接口类的方法上,控制方法的相关描述;

    @ApiImplicitParam 作用在接口方法上,描述单个参数信息,只能作用在方法上;

    @ApiImplicitParams 作用在接口方法上,@ApiImplicitParam参数组;

    @ApiParam 作用在接口方法上,描述单个参数信息,属性基本与@ApiImplicitParam一样,但可以作用在方法、参数、属性上;

    下面分别对每个注解的常用参数作讲解。

    @Api:

    value:字符串,对controller类的作用描述,代替原来的description(已过时),一般用此属性;

    tags:字符串数组,标签组,同样可以描述controller的作用;

    @ApiModel

    value:字符串,模型的简短别名,使得在文档的导航中便于识别;

    description:字符串,模型的附加描述;

    @ApiOperation

    value:字符串,方法的功能描述;

    tags:字符串数组,标签组,同样可以描述方法的作用;

    response:ClassType,显示指出返回的对象类型;在响应示例中会显示出改对象的字段以及示例、描述;

    code:响应代码,默认200,一般不改;

    @ApiModelProperty

    value:字符串,字段描述;

    required:boolean;指定参数是否必须,默认false;

    example:字符串,参数值的示例

    @ApiImplicitParam

    name:字符串,参数名;

    value:字符串,参数描述;

    defaultValue:字符串,参数默认值;

    required:boolean,标识是否必须传值,默认false;

    dataType:字符串,参数类型,可以是某个类名,也可以是基本数据类型的引用类名,如Integer;

    example:字符串,参数值示例;

    @ApiImplicitParams

    value:@ApiImplicitParam类型数组,当方法有多个@ApiImplicitParam参数时,需要放到@ApiImplicitParams注解中

    @ApiParam

    name:字符串,参数名;

    value:字符串,参数描述;

    defaultValue:字符串,设置默认值;

    required:boolean,是否必须,默认false;

    example:字符串,参数值示例;

     

     

    赞赏

    微信赞赏支付宝赞赏

    编程知识分享网,一个有趣的平台!
    编程知识分享网|编程教程|资源下载|源码下载 » swagger2.4注解大全

    常见问题FAQ

    免费下载或者VIP会员专享资源能否直接商用?
    本站所有资源版权均属于原作者所有,这里所提供资源均只能用于参考学习用,请勿直接商用。若由于商用引起版权纠纷,一切责任均由使用者承担。更多说明请参考 VIP介绍。
    提示下载完但解压或打开不了?
    最常见的情况是下载不完整: 可对比下载完压缩包的与网盘上的容量,若小于网盘提示的容量则是这个原因。这是浏览器下载的bug,建议用百度网盘软件或迅雷下载。若排除这种情况,可在对应资源底部留言,或 联络我们.。
    找不到素材资源介绍文章里的示例图片?
    对于PPT,KEY,Mockups,APP,网页模版等类型的素材,文章内用于介绍的图片通常并不包含在对应可供下载素材包内。这些相关商业图片需另外购买,且本站不负责(也没有办法)找到出处。 同样地一些字体文件也是这种情况,但部分素材会在素材包内有一份字体下载链接清单。
    关于编程知识分享网(www.ittce.com)
    编程知识分享网,一个有趣的平台,小心有毒!

    发表评论

    提供最优质的资源集合

    立即查看 了解详情
    升级SVIP尊享更多特权立即升级