Swagger注解传参
[@Api]
@ Api
用于声明Swagger资源API。 它有双重用途 - 它会影响资源列表_和_ API声明。 只有使用@ Api
注释的类才会被Swagger扫描。
在资源清单中,注释将转换为[资源对象]
在API声明中,它基本上将作为[API声明]本身的基础。
JAX-RS的用法是:
@Api(tags = "区域:/area", description = "地区的增删查改")@RestController@RequestMapping(value = "area", produces = {"application/json;charset=UTF-8"})@ApiResponses(value = {@ApiResponse(code = 400, message = "系统异常", response = RedisService.class),@ApiResponse(code = 401, message = "测试异常", response = AreaMapper.class)})public class AreaController {...}
[@ApiOperation]
@ ApiOperation
用于在API资源中声明单个操作。 操作被认为是路径和HTTP方法的唯一组合。 只扫描使用@ ApiOperation
注释的方法并添加API声明。
注释将影响Swagger输出的两个部分,[API对象],每个路径将创建一个,以及[操作对象],将根据@ApiOperation创建一个。 请记住,在使用Servlet时,@ Api
会在设置路径时影响API对象。
JAX-RS的用法是
@ApiOperation(value = "根据areaId获取地区", notes = "根据url的id来获取地区")@RequestMapping(value = " {areaId}", method = RequestMethod.GET)public Map<String, Object> getArea(@PathVariable("areaId") Integer areaId) {...}
[@ApiResponses], [@ApiResponse]
使用HTTP状态代码返回错误(或其他成功消息)是一种常见做法。 虽然操作的常规返回类型在[@ApiOperation]中定义,但应使用这些注释描述其余的返回代码。
@ ApiResponse
描述了具体的可能响应。 它不能直接在方法上使用,需要包含在@ ApiResponses
的数组值中(无论是否有一个响应或更多)。
如果响应伴随身体,也可以描述身体模型(每个响应一个模型)。
用法(JAX-RS,Servlet或其他)之间的使用没有区别:
@ApiOperation(value = "根据areaId获取地区", notes = "根据url的id来获取地区")@ApiImplicitParam(value = "地区id", name = "areaId", required = true, dataType = "int", paramType = "path", defaultValue = "1", example = "1")@RequestMapping(value = " {areaId}", method = RequestMethod.GET)@ApiResponses(value = {@ApiResponse(code = 400, message = "系统异常", response = RedisService.class),@ApiResponse(code = 401, message = "测试异常", response = AreaMapper.class)})public Map<String, Object> getArea(@PathVariable("areaId") Integer areaId) {...}
有关此注释,用法和边缘情况的更多详细信息,请查看javadoc ([@ApiResponses], [@ApiResponse]**.
[@ApiParam]
@ ApiParam
仅用于JAX-RS参数注释(@PathParam
,@ QueryParam
,@HeaderParam
,@ FormParam
和JAX-RS 2,@ BeanParam
)。 虽然swagger-core默认扫描这些注释,但@ ApiParam
可用于添加有关参数的更多详细信息,或在从代码中读取时更改值。
在Swagger规范中,这转换为[参数对象]。
Swagger将获取这些注释的value()
并将它们用作参数名称,并根据注释设置参数类型。 对于body参数(JAX-RS方法的单个输入参数),名称将自动设置为body
(根据Swagger规范的要求)。
如果存在,Swagger还将使用@ DefaultValue
的值作为默认值属性。
@RequestMapping(method = RequestMethod.POST)public Map<String, Object> addArea(@ApiParam(value = “地区名称”,required = true) String areaName,@ApiParam(value = “地区domain”,required = true) @RequestBody Area area) {…}
这里我们有两个参数。 第一个是areaName
,它是路径的一部分。 第二个是正文,在本例中是一个Area对象。 请注意,两个参数都将required
属性设置为true
。 对于@PathParam,这是多余的,因为默认情况下它是强制性的,不能被覆盖。
输出将是:
有关此注释,用法和边缘情况的更多详细信息,请查看 javadocs.
[@ApiImplicitParam], [@ApiImplicitParams]
您可能希望手动描述操作参数。 这可能有多种原因,例如:
- 使用不使用JAX-RS注释的Servlet.
- 想要隐藏定义的参数,并使用完全不同的定义覆盖它.
- 描述在到达JAX-RS实现之前过滤器或其他资源使用的参数.
由于可以包含几个参数,@ ApiImplicitParams
允许多个@ ApiImplicitParam
定义。
在Swagger规范中,这些转换为[Parameter Object]。
在隐式定义参数时,为Swagger的定义设置name
,dataType
和paramType
是很重要的。
@ApiImplicitParams({@ApiImplicitParam(name = “areaName”, value = “地区名称”, required = true, dataType = “string”, paramType = “query”),@ApiImplicitParam(name = “priority”, value = “地区编号”, required = false, dataType = “string”, paramType = “query”),@ApiImplicitParam(name = “id”, value = “地区id”, required = true, dataType = “long”, paramType = “query”)})@RequestMapping(value = “editArea”, method = RequestMethod.POST)public Map<String, Object> editArea(Area area) {…}
在上面的示例中,我们可以看到具有多个参数的Servlet定义。 dataType
可以是基元名称或类名称。 paramType
可以是Swagger支持的任何参数类型(有关更多详细信息,请参阅javadoc或规范).
有关此注释,用法和边缘情况的更多详细信息,请查看javadoc (@ApiImplicitParam, @ApiImplicitParams).
[@ApiModel]
Swagger-core在整个API内省中基于对它们的引用构建模型定义。 @ ApiModel
允许您操作模型的元数据,从简单的描述或名称更改到多态的定义。
这转换为Swagger规范中的[Model Object]。
在其基本功能中,您可以使用@ ApiModel
来更改模型的名称并为其添加描述:
@ApiModel(value = “区域domain”,description = “区域的数据库模型”)public class Area {…}
我们将模型的名称从Area
更改为区域domain
为了支持多态和继承,我们使用discriminator
和subTypes
字段。 两者都必须用于Swagger输出才有效。
“discriminator”字段必须是顶部模型中的字段,该字段将用于确定正在使用哪个子模型。 例如,如果您有一个Animal
类,其中Cat
,Dog
和Chicken
作为子类,则animalType
字段可以用作鉴别器来确定实际使用的是哪种动物。
subTypes
必须列出继承模型的类。 类本身不必从超类型继承。 事实上,Swagger不会自动读取扩展类,你必须在subTypes
中手动描述这些类,以便对它们进行解析。
@ApiModel(value="SuperModel", discriminator = "foo", subTypes = {SubModel.class})public class SuperModel {...}@ApiModel(value="SubModel")public class SubModel {...}
上面的代码片段是一个如何描述继承的简单示例。 注意SubModel不会扩展SuperModel。 以同样的方式,您可以添加多个继承类。 可以有任意数量的继承级别
For further details about this annotation, usage and edge cases, check out the javadocs.
[@ApiModelProperty]
虽然swagger-core将内省字段和setter / getter,但它也会读取和处理JAXB注释。 @ ApiModelProperty
允许控制Swagger特定的定义,例如允许的值和附加注释。 如果您想在某些情况下隐藏属性,它还提供其他过滤属性。
有关Swagger Spec中的相关信息,请查看Property Object.
@ApiModel(value = "区域domain",description = "区域的数据库模型")public class Area {@ApiModelProperty(value = "区域id", required = true, position = 1, example = "1")private Integer areaId;@ApiModelProperty(value = "区域名称", required = true, position = 2, example = "北京")private String areaName;@ApiModelProperty(value = "区域编号", required = true, position = 3, example = "10001")private Integer priority;@ApiModelProperty(value = "添加时间", required = false, position = 4, example = "2017-02-02")private Date createTime;@ApiModelProperty(value = "最后修改时间", required = false, position = 5, example = "2017-02-02")private Date lastEditTime;}
这是向模型属性添加简短描述的简单示例。 还可以观察到,虽然status
是一个String,但我们将其记录为只有三个可能的值。
有关此注释,用法和边缘情况的更多详细信息,请查看javadocs.
Name | Description |
---|---|
@Api | 将类标记为Swagger资源. |
@ApiImplicitParam | 表示API操作中的单个参数。 |
@ApiImplicitParams | 一个包装器,允许列出多个ApiImplicitParam对象。 |
@ApiModel | 提供有关Swagger模型的其他信息。 |
@ApiModelProperty | 添加和操作模型属性的数据. |
@ApiOperation | 描述针对特定路径的操作或通常是HTTP方法. |
@ApiParam | 鈥为操作参数添加其他元数据. |
@ApiResponse | 描述操作的可能响应. |
@ApiResponses | 鈥一个包装器,允许列出多个ApiResponse对象. |
@Authorization | 鈥声明要在资源或操作上使用的授权方案. |
@AuthorizationScope | 鈥描述OAuth2授权范围. |
Swagger注解传参相关推荐
- Swagger注解 传参
[@Api] @ Api用于声明Swagger资源API. 它有双重用途 - 它会 影响资源列表_和_ API声明. 只有使用@ Api注释的类才会被Swagger扫描. 在资源清单中,注释将转换为[ ...
- Spring Swagger URL传参问题(转)
代码例子: @ApiOperation(value="获取用户详细信息", notes="根据url的id来获取用户详细信息")@ApiImplicitPara ...
- Springboot传参详解
作者简介 作者名:编程界明世隐 简介:CSDN博客专家,从事软件开发多年,精通Java.JavaScript,博主也是从零开始一步步把学习成长.深知学习和积累的重要性,喜欢跟广大ADC一起打野升级,欢 ...
- @modelattribute注解用postman测试怎么传参_谁要是再敢用Map传参,我过去就是一JIO...
还记得上次我写过一篇关于实际项目代码分层和规划的文章<看完这篇,别人的开源项目结构应该能看懂了>, 在文尾处提到过一些注意事项,其中第一条就是: Contorller层参数传递建议不要使用 ...
- java中注解动态传参_SpringMVC之注解、传参、返回值及拦截器
1. 注解式开发之annotation-driven解释 (1) mvc注解驱动在哪个文件中配置? Springmvc.xml (2) 配置mvc注解驱动使用哪个标签? 2. 注解式开发之视图解析器 ...
- JAVA——实现json bean实体类的传参校验模板及注解详解
关注微信公众号:CodingTechWork,一起学习进步. 引言 在java开发中,经常需要和外界系统进行参数对接,api设计中难免会遇到json传参不一致的情况,虽然纸面或者接口规范约束了应该 ...
- SpringMVC 使用注解时控制器传参
自动注入 默认方法的参数名和网页的属性名相同,会自动注入(自动转换类型) Tips:若方法的参数名和网页的属性名并不相同,可使用注解 @RequestParam(value="网页的属性名& ...
- ajax deletemapping,springmvc使用put,delete方法传参问题,以及使用@PutMapping注解和@DeleteMapping注解...
首先我们要知道@PutMapping,@DeleteMapping的作用: @PutMapping:"对应修改操作,表明是一个修改URL映射". @DeleteMapping:&q ...
- SpringMVC→简介、MVC、SpringMVC工作原理、Maven搭建第一个SpringMVC、请求参数接收、重定向、文件上传、AJAX异步访问、请求参数接收绑定JSON、@注解及传参
MVC SpringMVC工作原理 Maven搭建第一个SpringMVC 目录结构 web.xml *-servlet.xml Controller请求处理类 跳转页面 Maven运行服务器项目 浏 ...
- SSM8==纯注解SSM项目:实现单表CRUD、事务、自定义异常和统一异常处理、RESTFUL风格接口、统一返回值格式(状态码、内容、消息)、JSON传参、axios、vue.js、elementUI
环境:IDEA2021+JDK8+MAVEN3.8+TOMCAT7插件 前端:axios.vue.js.elementUI 后端:见POM.XML相关依赖,主要有数据库MySQL5.7 ,数据源Dru ...
最新文章
- Volatile 关键字 内存可见性
- 欧拉降幂及其扩展欧拉降幂
- 定制化Azure站点Java运行环境(1)
- LeetCode上稀缺的四道shell编程题解析
- python图片内容长度识别_Python实现识别图片内容的方法分析
- android功耗(23)---gps定位开发省电要点
- 阿里云云计算 9 弹性裸金属服务器(神龙)
- sqlplus linux 连接数据库,sqlplus连接Oracle
- 12.UniT:Multimodal Multitask Learning with a Unified Transformer
- Stata+PSM:倾向得分匹配分析简介
- jpg转bmp c语言 linux,C语言实现BMP转换JPG的方法
- 《不能承受的生命之轻》--米兰·昆德拉
- JAVA教材(推荐新手学习)
- 颜色类中英文词汇大全(3)
- Spring框架——IOC、DI
- 赛事启动 |香港科大-杰瑞集团 2022【人工智能】百万奖金国际创业大赛
- 源码分析 | 手写mybait-spring核心功能(干货好文一次学会工厂bean、类代理、bean注册的使用)
- Linux内存控制器(二)
- 干掉鼠标!用这 4 款 App 大幅提升 Mac 键盘效率
- vxi11协议服务器的实现,基于DSP和VXI-11协议的LXI仪器控制与实现.pdf