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或其他)之间的使用没有区别:
@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.
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注解 传参相关推荐
- 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 ...
最新文章
- 调侃 -- 刚入职时的单纯
- 迭代法移动盘子java,算法学习--日记(牛顿迭代法)
- 如果三十年前有这些AI技术,可可西里的悲剧不会发生
- 编者序:初衷、计划、要求、优势、目标和展望
- classlink error java,java – EclipseLink:对MappedSuperclass的查询失败
- x的平方根—leetcode69
- Spring Integration关键案例与现实生活场景
- python turtle 绘图速度用函数会快吗_有趣的Python turtle绘图
- sql开启mysql远程连接_SQLServer2008设置开启远程连接
- cmake中添加引用动态链接_C和C++使用对方编译的动态链接库
- 小D课堂-SpringBoot 2.x微信支付在线教育网站项目实战_3-2.使用Mybatis注解开发视频列表增删改查...
- 图像处理笔记(0)---- 图像空间知识
- 打砖块 java_java实现打砖块小游戏
- 2021年涡阳四中高考成绩查询,振奋人心,全是省重点!高考成绩出来了,涡阳家长快来看看!...
- 免信任型计算的扩容模型
- 《境外汇款申请书》填报说明
- 水到底是一种液体还是两种液体
- 知识文库杂志知识文库杂志社知识文库编辑部2022年第14期目录
- 今日份安利:epub格式转换成mobi方法哪个好?
- swing应用-简单记事本