讲解内容

1. swagger常用到的注解的解释
2. SpringMvc中控制层类中使用这些注解

swagger常用到的注解的解释

在pom.xml文件中添加包依赖：swagger-annotations-1.5.10.jar

所有注解：

常用到的注解有：

• Api
• ApiModel
• ApiModelProperty
• ApiOperation
• ApiParam
• ApiResponse
• ApiResponses
• ResponseHeader

Api 标记一个Controller类做为swagger 文档资源

使用方式：

@Api(value = "/user", description = "Operations about user")

与Controller注解并列使用。 属性配置：

属性名称	备注	默认值
value	url的路径值
tags	如果设置这个值、value的值会被覆盖
description	对api资源的描述
basePath	基本路径可以不配置
position	如果配置多个Api 想改变显示的顺序位置
produces	For example, "application/json, application/xml"
consumes	For example, "application/json, application/xml"
protocols	Possible values: http, https, ws, wss.
authorizations	高级特性认证时配置
hidden	配置为true 将在文档中隐藏

在SpringMvc中的配置如下：

@Controller
@RequestMapping(value = "/api/pet", produces = {APPLICATION_JSON_VALUE, APPLICATION_XML_VALUE})
@Api(value = "/pet", description = "Operations about pets")
public class PetController {}

定义后swagger效果图： 

ApiOperation每一个url资源的定义

使用方式：

@ApiOperation(value = "Find purchase order by ID",notes = "For valid response try integer IDs with value <= 5 or > 10. Other values will generated exceptions",response = Order,tags = {"Pet Store"})

与Controller中的方法并列使用。

属性配置：

属性名称	备注	默认值
value	url的路径值
tags	如果设置这个值、value的值会被覆盖
notes	对api资源的描述
response	返回的对象
responseContainer	这些对象是有效的 "List", "Set" or "Map".，其他无效
responseReference	可以不配置
httpMethod	可以接受 "GET", "HEAD", "POST", "PUT", "DELETE", "OPTIONS" and "PATCH"
position	如果配置多个Api 想改变显示的顺序位置
produces	同 Api中的定义
consumes	同 Api中的定义
protocols	同 Api中的定义
authorizations	同 Api中的定义
hidden	同 Api中的定义
code	http的状态码 默认 200
extensions	扩展属性

在SpringMvc中的配置如下：

@RequestMapping(value = "/order/{orderId}", method = GET)@ApiOperation(value = "Find purchase order by ID",notes = "For valid response try integer IDs with value <= 5 or > 10. Other values will generated exceptions",response = Order.class,tags = { "Pet Store" })public ResponseEntity<Order> getOrderById(@PathVariable("orderId") String orderId)throws NotFoundException {Order order = storeData.get(Long.valueOf(orderId));if (null != order) {return ok(order);} else {throw new NotFoundException(404, "Order not found");}}

swagger效果图： 

ApiParam请求属性

使用方式：

public ResponseEntity<User> createUser(@RequestBody @ApiParam(value = "Created user object", required = true)  User user)

与Controller中的方法并列使用。

属性配置：

属性名称	备注	默认值
name	属性名称
value	属性值
defaultValue	默认属性值
allowableValues	可以不配置
required	是否属性必填
access	不过多描述
allowMultiple	默认为false
hidden	隐藏该属性
example	举例子
examples

在SpringMvc中的配置如下：

 public ResponseEntity<Order> getOrderById(@ApiParam(value = "ID of pet that needs to be fetched", allowableValues = "range[1,5]", required = true)@PathVariable("orderId") String orderId)

ApiResponse响应配置

使用方式：

@ApiResponse(code = 400, message = "Invalid user supplied")

与Controller中的方法并列使用。 属性配置：

属性名称	备注	默认值
code	http的状态码
message	描述
response	默认响应类 Void
reference	参考ApiOperation中配置
responseHeaders	参考 ResponseHeader 属性配置说明
responseContainer	参考ApiOperation中配置

在SpringMvc中的配置如下：

 @RequestMapping(value = "/order", method = POST)@ApiOperation(value = "Place an order for a pet", response = Order.class)@ApiResponses({ @ApiResponse(code = 400, message = "Invalid Order") })public ResponseEntity<String> placeOrder(@ApiParam(value = "order placed for purchasing the pet", required = true) Order order) {storeData.add(order);return ok("");}

效果图展示： 

ApiResponses相应集配置

使用方式：

 @ApiResponses({ @ApiResponse(code = 400, message = "Invalid Order") })

与Controller中的方法并列使用。 属性配置：

属性名称	备注	默认值
value	多个ApiResponse配置

在SpringMvc中的配置如下：

 @RequestMapping(value = "/order", method = POST)@ApiOperation(value = "Place an order for a pet", response = Order.class)@ApiResponses({ @ApiResponse(code = 400, message = "Invalid Order") })public ResponseEntity<String> placeOrder(@ApiParam(value = "order placed for purchasing the pet", required = true) Order order) {storeData.add(order);return ok("");}

ResponseHeader相应配置

使用方式：

@ResponseHeader(name="head1",description="response head conf")

与Controller中的方法并列使用。 属性配置：

属性名称	备注	默认值
name	响应头名称
description	头描述
response	默认响应类 Void
responseContainer	参考ApiOperation中配置

在SpringMvc中的配置如下：

@ApiModel(description = "群组")

ApiModel相应配置

使用方式：

属性配置：

属性名称	备注	默认值
value	默认为类的名称
description	对该类的描述
parent	可以不配置
discriminator	可以不配置
subTypes	可以不配置
reference	引用配置可以不考虑

在SpringMvc中的配置如下：

@ApiModel(description = "群组")
public class UamGroup {}

ApiModelProperty相应配置

使用方式：

@ApiModelProperty(required = true, value = "群组的Id")

属性配置：

属性名称	备注	默认值
value	属性描述
name	如果配置覆盖属性名称
allowableValues	参考ApiParam配置项项
access	可以不配置
notes	没有使用
dataType	数据类型
required	参考ApiParam配置项项
position	参考ApiOperation配置项
hidden	参考ApiOperation配置项
example	参考ApiParam配置项项
readOnly
reference	参考ApiParam配置项项

在SpringMvc中的配置如下：

@ApiModelProperty(required = true, value = "群组的Id")private String groupId;

转自：https://my.oschina.net/zzuqiang/blog/793606

swagger注解类说明相关推荐

1. 【SpringBoot】mybatis 自动生成swagger注解，及普通查询sql

   1.项目结构 1.pom文件中的引入 <?xml version="1.0" encoding="UTF-8"?> <project xmln ...

2. java 生成并覆盖文件,基于mybatis-plus生成不被覆盖的文件并支持swagger注解

   情况是这样的: 原本mybatis-plus的框架的模板是不支持swagger的注解的,需要手动写. 自己折腾了1个多小时,建立在mybatis-plus的基础上进行修改.可以选择生成文件时,不覆盖某 ...

3. 保存系统的操作日志，通过swagger注解获取请求描述（通用版本）

   版权声明:本文为博主原创文章,遵循 CC 4.0 BY-SA 版权协议,转载请附上原文出处链接和本声明. 大数据系列文章目录 前言 系统之前没有全局的记录操作日志,只是个别单个功能记录了操作日志,这样 ...

4. 什么是swagger以及swagger注解详解

   1.什么是swagger Swagger是一个规范和完整的框架,用于生成.描述.调用和可视化RESTful风格的Web服务.简单来说,Swagger是一个功能强大的接口管理工具,并且提供了多种编程语言 ...

5. 【swagger】Swagger注解介绍

   Swagger注解介绍 1.swagger注解 @ApiModel: 用于类,表示对类进行说明,用于参数用实体类接收 @ApiProperty:用于字段,表示对model属性的说明或者数据操作更改 @ ...

6. @aspect注解类不生效_springboot：@Transactional注解 VS @Service注解

   1. Transactional注解与Service/Component注解冲突? 之前遇到一个神奇的事情--用Transactional注解的方法,数据处理了一半,后面的数据处理抛出异常后,没有回滚 ...

7. hyperf自定义注解类_swoole学习六hyperf注解的使用

   什么是注解 对于开发java的同学来说注解是一种再熟悉不过的东西了,在代码中一般无处不见注解的存在.php对于注解并没有原生支持,但是有人做了公共包可以来使用. 那注解是什么,简单来说注解是给程序扩展 ...

8. java自定义注解类

   一.前言 今天阅读帆哥代码的时候,看到了之前没有见过的新东西, 比如java自定义注解类,如何获取注解,如何反射内部类,this$0是什么意思? 于是乎,学习并整理了一下. 二.代码示例 import ...

9. Springboot 注解类里面public @interface xxx 什么意思

   @interface 不是interface,是注解类  定义注解 是jdk1.5之后加入的,java没有给它新的关键字,所以就用@interface 这么个东西表示了  这个注解类,就是定义一个可用 ...

10. swagger注解说明_swagger2常用注解说明

    原文:https://blog.csdn.net/u014231523/article/details/76522486 说明: 1.这里使用的版本:springfox-swagger2(2.4)sp ...

最新文章

1. VC:CString用法整理(转载)
2. 干货！Java 学习路线指南，看这文就够了！
3. Android自定义组合控件
4. 如何解决get和post乱码问题？
5. Ubuntu12.04 安装vim出错
6. 框架、文档、视图类之间的调用关系
7. 算符“.*”和“-*”，用于“成员指针”
8. leader选举的源码分析-FastLeaderElection
9. subline类似less的html插件,29个常用 Sublime Text 插件推荐
10. php文本文件操作,文本文件操作的php类
11. 文字层一点就变红_《蚂蚁前端研发最佳实践》文字稿
12. 福布斯中国2020科技女性榜：蓝港互动廖明香、百度李莹等上榜
13. Android开发笔记（一百三十六）可折叠工具栏布局CollapsingToolbarLayout
14. paip.c#.nett 系统托盘动态图标闪烁图标
15. 线性代数及其应用 知识整理
16. Linux下vi编辑器的使用方法
17. golangci-lint timeout
18. 华为云盘（华为云空间）免费空间
19. 2020年陕西省高等职业院校技能大赛信息安全管理与评估赛项竞赛手册
20. 这是我见过最秀的代码 。。。

热门文章

1. php实现公众号支付demo,PHP微信公众号支付demo
2. 大学物理第三版朱峰课后答案详解_大学物理 第三版 [朱峰 主编] 2014年版
3. 十大排序算法-桶排序（c语言实现）
4. jasperReports导出PDF字体加粗等样式失效问题
5. HTML+CSS网页设计视频教程
6. 线性分类器定义和局限性
7. stream流转toMap的使用以及Key重复的解决
8. 〖EXP〗NSA MS17010永恒之蓝漏洞一键工具
9. Linux配置开机自动挂载WindowsNTFS硬盘分区
10. 易语言精益模块json_精易模块|精易模块下载 v3.46 官方免费版_最火软件站