Swagger Annotation 详解(建议收藏)
转载:https://www.jianshu.com/p/b0b19368e4a8
在软件开发行业,管理文档是件头疼的事。不是文档难于撰写,而是文档难于维护,因为需求与代码会经常变动,尤其在采用敏捷软件开发模式的系统中。好的工具能够提高团队沟通效率,保证系统质量以及缩短项目的交付周期。反之,差的管理工具,会严重影响沟通效率,增加系统bug数量,并且延误产品的上线日期。所以选用合理与合适的软件开发文档管理工具十分重要,真正让开发者做到“高高兴兴地把活干完,早点回家吃饭打游戏”。
Swagger是什么?
Swagger 是一款目前世界最流行的API管理工具。但目前Swagger已经形成一个生态圈,能够管理API的整个生命周期,从设计、文档到测试与部署。Swagger有几个重要特性:
- 代码侵入式注解
- 遵循YAML文档格式
- 非常适合三端(PC、iOS及Android)的API管理,尤其适合前后端完全分离的架构模式。
- 减少没有必要的文档,符合敏捷开发理念
- 功能强大
Swagger拥有众多不同语言和平台的开源实现与工具,主要有:
- Swagger UI,基于Swagger-compliant API的一套可以展示优美文档的Web应用。
- Swagger Editor,一款以YAML格式编辑与管理API的工具,同时支持JSON格式的文档描述。
- Swagger-Core,Swagger的Java/Scala实现,并已集成 JAX-RS (Jersey, Resteasy, CXF...), Servlets与Play Framework。
- Swagger-JS,Swagger的Javascript版本实现。
更多的列表可以参考此处。
尤其要注意的是Swagger UI,它是Swagger的Web页面展现形式,能够对符合swagger规范的文件进行解析与显示。通过友好的页面,可以对API进行分组管理、文档显示以及实现mock测试。所以在大多数情形下,都使用Swagger UI实现对API的管理与展现。
Swagger UI的安装
Swagger UI是一个Web应用程序,所以可以单独部署使用。可以从这里下载Swagger UI,然后根据文档说明进行安装与配置。
对于以Java与Spring Boot作为后台开发语言和框架而言,专门有一个开源插件springfox同时实现了Swagger UI及Swagger-Core。这个插件可以很方便地利用构建工具Maven或Gradle引入与管理。本文以下部分将着重讲述有关这个插件的swagger相关注解。
Swagger Annotation分析
对于java版本的swagger annotations比较多,本着精简与必要的原则,不会对所有annotation及每个annotation的所有属性进行描述,仅选择重要且工作中常用的部分进行说明。
Swagger的annotation主要分为两类,一类是对Model的注解;另一类是对API的注解。
API的注解
对于API的设计,一般倾向于将功能相同的API归集为一组。在Spring Boot中,利用Controller来实现,每个Controller里包含若干个REST API,而每个API都有输入及输出值。所以swagger对API的注解也是参照这个层级来划分与实现的。其逻辑结果如下图:
- @Api
该注解将一个Controller(Class)标注为一个swagger资源(API)。在默认情况下,Swagger-Core只会扫描解析具有@Api注解的类,而会自动忽略其他类别资源(JAX-RS endpoints,Servlets等等)的注解。该注解包含以下几个重要属性:- tags
API分组标签。具有相同标签的API将会被归并在一组内展示。 - value
如果tags没有定义,value将作为Api的tags使用 - description
API的详细描述,在1.5.X版本之后不再使用,但实际发现在2.0.0版本中仍然可以使用
- tags
- @ApiOperation
在指定的(路由)路径上,对一个操作或HTTP方法进行描述。具有相同路径的不同操作会被归组为同一个操作对象。不同的HTTP请求方法及路径组合构成一个唯一操作。此注解的属性有:- value
对操作的简单说明,长度为120个字母,60个汉字。 - notes
对操作的详细说明。 - httpMethod
HTTP请求的动作名,可选值有:"GET", "HEAD", "POST", "PUT", "DELETE", "OPTIONS" and "PATCH"。 - code
默认为200,有效值必须符合标准的HTTP Status Code Definitions。
- value
- @ApiImplicitParams
注解ApiImplicitParam的容器类,以数组方式存储。 - @ApiImplicitParam
对API的单一参数进行注解。虽然注解@ApiParam同JAX-RS参数相绑定,但这个@ApiImplicitParam注解可以以统一的方式定义参数列表,也是在Servelet及非JAX-RS环境下,唯一的方式参数定义方式。注意这个注解@ApiImplicitParam必须被包含在注解@ApiImplicitParams之内。可以设置以下重要参数属性:- name
参数名称 - value
参数的简短描述 - required
是否为必传参数 - dataType
参数类型,可以为类名,也可以为基本类型(String,int、boolean等) - paramType
参数的传入(请求)类型,可选的值有path, query, body, header or form。
- name
- @ApiParam
增加对参数的元信息说明。这个注解只能被使用在JAX-RS 1.x/2.x的综合环境下。其主要的属性有:- required
是否为必传参数 - value
参数简短说明
- required
- @ApiResponses
注解@ApiResponse的包装类,数组结构。即使需要使用一个@ApiResponse注解,也需要将@ApiResponse注解包含在注解@ApiResponses内。 - @ApiResponse
描述一个操作可能的返回结果。当REST API请求发生时,这个注解可用于描述所有可能的成功与错误码。可以用,也可以不用这个注解去描述操作的返回类型,但成功操作的返回类型必须在@ApiOperation中定义。如果API具有不同的返回类型,那么需要分别定义返回值,并将返回类型进行关联。但Swagger不支持同一返回码,多种返回类型的注解。注意:这个注解必须被包含在@ApiResponses注解中。- code
HTTP请求返回码。有效值必须符合标准的HTTP Status Code Definitions。 - message
更加易于理解的文本消息 - response
返回类型信息,必须使用完全限定类名,比如“com.xyz.cc.Person.class”。 - responseContainer
如果返回类型为容器类型,可以设置相应的值。有效值为 "List", "Set" or "Map",其他任何无效的值都会被忽略。
- code
Model的注解
对于Model的注解,Swagger提供了两个:@ApiModel及@ApiModelProperty,分别用以描述Model及Model内的属性。
- @ApiModel
提供对Swagger model额外信息的描述。在标注@ApiOperation注解的操作内,所有的类将自动被内省(introspected),但利用这个注解可以做一些更加详细的model结构说明。主要属性有:- value
model的别名,默认为类名 - description
model的详细描述
- value
- @ApiModelProperty
对model属性的注解,主要的属性值有:- value
属性简短描述 - example
属性的示例值 - required
是否为必须值
- value
关于Token问题
考虑到安全的问题,每次请求API需要对用户进行验证与授权。目前主流的验证方式采用请求头部(request header)传递token,即用户登录之后获取一个token,然后每次都使用这个token去请求API。如果想利用swagger-UI进行API测试,必须显式为每个需要验证的API指定token参数。这时可以为每个操作添加一个注解@ApiImplicitParams,具体代码如下:
<code>
@ApiImplicitParams({@ApiImplicitParam(name = "TOKEN", value = "Authorization token", required = true, dataType = "string", paramType = "header")})
</code>
作者:杨梅泡酒
链接:https://www.jianshu.com/p/b0b19368e4a8
来源:简书
简书著作权归作者所有,任何形式的转载都请联系作者获得授权并注明出处。
转载于:https://www.cnblogs.com/ceshi2016/p/10511959.html
Swagger Annotation 详解(建议收藏)相关推荐
- 大型企业中如何批量管理千万台服务器之ansible自动化运维工具详解 [⭐建议收藏⭐]
文章目录 ansible 自动化运维工具 详解 关于作者 作者介绍 一.ansible 概述 1.1 ansible 概述 1.2 是什么要使用 ansible 1.3 ansible 功能 1.4 ...
- Spring三十五问,四万字+五十图详解 建议收藏
这节我们来搞定另一个面试必问知识点--Spring. 有人说,"Java程序员都是Spring程序员",老三不太赞成这个观点,但是这也可以看出Spring在Java世界里举足轻重的 ...
- 前后端交互详解(建议收藏)
1.前后端认知 相信很多人心里都有一个疑惑:我⼀个前端, 为什么要学习后端? 那么到底什么是前端? 什么是后端? 什么是数据库? 1.1 基本组织架构 我们是⼀个 前端开发⼯程师 还有⼀个⼯作叫做后端 ...
- 跨行合并居中html标记语言,[前端Web]HTML语法最全解-建议收藏
原标题:[前端Web]HTML语法最全解-建议收藏 1. 标签全解 1.1 文件标记 作用:文档声明标签.定义该文档是html5的文档,位于标签前面 详解: HTML总共有很多的版本,那么浏览器怎么知 ...
- Java注解(Annotation)详解
转: Java注解(Annotation)详解 幻海流心 2018.05.23 15:20 字数 1775 阅读 380评论 0喜欢 1 Java注解(Annotation)详解 1.Annotati ...
- Apache 的 httpd.conf 属性详解(收藏)
ServerRoot "/usr/local" ServerRoot用于指定守护进程httpd的运行目录,httpd在启动之后将自动将进程的当前目录改变为这个目录,因此如果设置文件 ...
- swagger使用详解
1:认识Swagger Swagger 是一个规范和完整的框架,用于生成.描述.调用和可视化 RESTful 风格的 Web 服务.总体目标是使客户端和文件系统作为服务器以同样的速度来更新.文件的方法 ...
- Java Annotation详解
http://djjchobits.iteye.com/blog/569000 元数据的作用 如果要对于元数据的作用进行分类,目前还没有明确的定义,不过我们可以根据它所起的作用,大致可分为三类: l ...
- 四十一,java中Annotation详解
2019独角兽企业重金招聘Python工程师标准>>> 1.Annotation简介 Annotation实际上表示一种注释的语法,java中最早的程序是提倡代码与配置相分离,而最新 ...
最新文章
- python pip指令_python 常用 pip 命令合集
- mysql读取sql脚本_Pandas直接读取sql脚本的方法
- mysql 过程和函数 变量的值_MySQL数据库提升篇-----存储过程和函数
- asp.net html table,在ASP.NET中利用HtmlTable动态创建表格 | 学步园
- android nuwa2,android热更新
- 无线路由器——多路由器无线桥联解决方案
- 计算机程序的构造和解释 python_SICP Python 描述 第三章 计算机程序的构造和解释 3.1 引言...
- C++/C--set常见用法详解【转载】
- C基础(36——40)
- JWT教程_3 oauth和JWT 整合
- c#实现txt转化为excel
- mini2440 SD卡脱机烧写恢复
- 6个免抠素材网站,免费可商用
- SOM网络(Kohonen自组织网络)学习第二篇
- linux双系统优先开启_更改双系统启动菜单(启动顺序)的2种方法
- 最强大脑记忆曲线(7)——“复习页面”逻辑实现
- QFD修改工作流并重新发布中的问题
- ps的切片用来转换html,Photoshop切片导出HTML+CSS
- M1芯片MacBook安装Kali虚拟机----正版、免费、手把手
- #名词区别篇:px、em、rem、rpx、vh、vw、vmin 、vmax、%用法 与 区别
热门文章
- dist包编译html_npm package开发指南-包内容篇
- centos7卸载docker_使用 Docker 部署 Spring Cloud 项目详细步骤
- shell给python传变量_python和shell 传递变量
- mysql se_常见的MySQL命令
- asp.net控件全部清空、全部启用、全部禁用方法
- lua游戏脚本实例源码_Lua脚本引擎教程(六):饥荒Lua脚本系统
- python获取局域网通过guest开放的软件_python构建SSH僵尸网络
- C语言:编写程序,打开文本文件stu.txt,读出文件内容,将其中的字符‘s’删除,将修改后的内容存到student.txt文件中。
- android wear系统源码,android wear5.1怎么样 android wear5.1更新评测
- mysql与其他数据库的区别_mysql与其他数据库的区别