Swagger Annotation 详解（建议收藏）

在软件开发行业，管理文档是件头疼的事。不是文档难于撰写，而是文档难于维护，由于需求与代码会常常变更，尤为在采用敏捷软件开发模式的系统中。好的工具可以提升团队沟通效率，保证系统质量以及缩短项目的交付周期。反之，差的管理工具，会严重影响沟通效率，增长系统bug数量，而且延误产品的上线日期。因此选用合理与合适的软件开发文档管理工具十分重要，真正让开发者作到“高高兴兴地把活干完，早点回家吃饭打游戏”。java

Swagger是什么？

Swagger 是一款目前世界最流行的API管理工具。但目前Swagger已经造成一个生态圈，可以管理API的整个生命周期，从设计、文档到测试与部署。Swagger有几个重要特性：git

代码侵入式注解
遵循YAML文档格式
很是适合三端（PC、iOS及Android）的API管理，尤为适合先后端彻底分离的架构模式。
减小没有必要的文档，符合敏捷开发理念
功能强大

Swagger拥有众多不一样语言和平台的开源实现与工具，主要有：github

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版本实现。

更多的列表能够参考此处。spring

尤为要注意的是Swagger UI，它是Swagger的Web页面展示形式，可以对符合swagger规范的文件进行解析与显示。经过友好的页面，能够对API进行分组管理、文档显示以及实现mock测试。因此在大多数情形下，都使用Swagger UI实现对API的管理与展示。后端

API分组列表

API Mock测试

Swagger UI的安装

Swagger UI是一个Web应用程序，因此能够单独部署使用。能够从这里下载Swagger UI，而后根据文档说明进行安装与配置。api

对于以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的注解也是参照这个层级来划分与实现的。其逻辑结果以下图：

Swagger Annotation 逻辑结构图

@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版本中仍然可使用
@ApiOperation
在指定的（路由）路径上，对一个操做或HTTP方法进行描述。具备相同路径的不一样操做会被归组为同一个操做对象。不一样的HTTP请求方法及路径组合构成一个惟一操做。此注解的属性有：
- value
  对操做的简单说明，长度为120个字母，60个汉字。
- notes
  对操做的详细说明。
- httpMethod
  HTTP请求的动做名，可选值有："GET", "HEAD", "POST", "PUT", "DELETE", "OPTIONS" and "PATCH"。
- code
  默认为200，有效值必须符合标准的HTTP Status Code Definitions。
@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。
@ApiParam
增长对参数的元信息说明。这个注解只能被使用在JAX-RS 1.x/2.x的综合环境下。其主要的属性有：
- required
  是否为必传参数
- value
  参数简短说明
@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"，其余任何无效的值都会被忽略。

Model的注解

对于Model的注解，Swagger提供了两个：@ApiModel及@ApiModelProperty，分别用以描述Model及Model内的属性。

@ApiModel
提供对Swagger model额外信息的描述。在标注@ApiOperation注解的操做内，全部的类将自动被内省（introspected），但利用这个注解能够作一些更加详细的model结构说明。主要属性有：
- value
  model的别名，默认为类名
- description
  model的详细描述
@ApiModelProperty
对model属性的注解，主要的属性值有：
- value
  属性简短描述
- example
  属性的示例值
- required
  是否为必须值

关于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>