为什么要实现API文档化？
API文档化有利于前后端分离的开展。随着开发方式全面转成前后端分离，前端和后端的唯一沟通就在API层面。在没有文档化之前，开发人员只能口头的交代并反复理解每个接口参数和返回值，这个过程相当不稳定，变化频繁。而通过API文档化后，可以通过文档的清晰定义，使得前后端人员减少无畏沟通，并在理解上保持一致；
API文档化有利于接口自动化测试。公司马上上马接口自动化测试，对接口参数和返回值要通过Json方式导入自动化测试程序。而用特殊工具生成的API文档，可以直接输出json格式的文档，简化了测试流程，减轻了开发人员的工作量；
API文档化有利于系统文档建设。开发人员不愿意写文档，写注释。而为了以上两个目的必须要求开发人员在编码的同时补充相关的API描述，而通过一个相对稳定成熟和趁手的工具可以大大减轻文档的工作量，做到事半功倍。
Swagger和spring-boot-starter-swagger
Swagger是业界比较流行的实现API文档化的工具。优点有
- 通过在项目中引入Swagger，可以使用简单的Annotation，就实现了API文档化；
- Swagger提供标准的json或yaml文档，方便做进一步解析，典型应用是接口自动化测试；
- 页面可以直接进行测试（try-it-out功能，部分替代Postman）；
- Swagger还提供类似于github的SwaggerHub，相当于公共的API文档集散地。
Swagger的项目主页：https://swagger.io/
为了将Swagger和公司现有技术框架相结合，在网上发现了这么一个小项目spring-boot-starter-swagger，将公司项目和Swagger的集成又简化了一步，特此向作者表示感谢。
作者在简书上的介绍文章：https://www.jianshu.com/p/91c5a8565a45
主要优点：
- 引入足够简单，只需要2步（如果有Shiro就是3步）
- 方便的Swagger开关
- 支持yaml格式的配置
- 支持API的分组显示（在API过多的情况下非常好用）
- 支持JSR-303校验注解（@Min, @Max, @Pattern等）
- 依然在维护完善，逐步增加更多配置和开关
Swagger引入方法
- pom文件引入
<dependency>
<groupId>com.spring4all</groupId>
<artifactId>spring-boot-starter-swagger</artifactId>
<version>1.5.1.RELEASE</version>
</dependency>
- 主文件加Annotation
@SpringBootApplication
@EnableSwagger2Doc
public calss TestSwaggerApplication{
- 增加Shiro的anon设置（防止被登录转向）
client:
filters:
filter:
chain:
definitions: /swagger-ui.html=anon;/webjars/**=anon;/swagger-resources/**=anon;/v2/api-docs/**=anon;/**=authc;
- 配置文件
配置文件统一放到了项目的application.yml中，稍后计划使用新的文件，并采用引入的方式实现配置文件的分离
4.1 公共信息
定义整个项目的总体信息。
swagger:
# 公共信息
enabled: true
title: swagger-demo
description: 一个Swagger测试项目
version: 0.1-SNAPSHOT
# 许可证及服务条款信息
license:
licenseUrl:
termsOfServiceUrl:
contact:
name: Carisma
url:
email: carisma.zhao@gmail.com
base-package: me.learning.swagger
4.2 分组策略
分组策略指的是在整个项目中，将不同类型的API接口分散到不同的页面，方便查看和测试。
# 分组策略
docket:
apiForMe:
title: Myself
description: 开放给自己的接口
base-path: /api/myself/**
apiForOthers:
title: Others
description: 作为其他人的接口
base-path: /api/others/**
4.3 公共参数和通用错误码
像每个接口都需要鉴权这种参数，可以在配置文件中统一定义，这样省去每个接口再写的麻烦，也能兼顾页面的测试。
# 公共参数
global-operation-parameters[0]:
name: TOKEN
description: 鉴权
modelRef: string
parameterType: header
# 公共参数写成requierd, 对于不需要登录的接口随便写一个字符串即可
required: true
# 通用返回错误码
apply-default-response-messages: true
global-response-message.get[0]:
code: 401
message: 401错误
global-response-message.get[1]:
code: 500
message: 后端错误
modelRef: ERROR
Swagger的效果查看
以上配置完成后，Swagger直接可以生成文档，而不需要单独在每个需要显示的API上添加Annotation，当然下面会讲到如果需要更清晰的显示，还要使用注解，使用注解后，查看方式依然是以下两种。
- API文档：在浏览器中输入
localhost:9120/swagger-ui.html即可。端口号为Application的启动端口； - Json文件：如果没有分组，则直接使用
localhost:9120/swagger-ui.html/v2/api-doc，即显示API的Json格式（包括对model的解析），如果使用了分组，则需要每个分组单独显示，例如localhost:9120/swagger-ui.html/v2/api-doc/?group=apiForMe
Annotation使用详解
要想详细的、切合实际的展示API的内容与要求，则必须在API和Model上加单独的注解，官方JavaDoc虽然不是很详细，但是作为参考也够了（剩下的就是自己试了）：
http://docs.swagger.io/swagger-core/current/apidocs/index.html?io/swagger/annotations/Api.html
其中常用的有以下几个，亲测后有些需要详细说明：
@Api
加在需要自定义注解的API类（*Controller）上。这个注解没有什么属性需要说的，其中value比较奇葩，官方说法是隐含的代替tag的作用。（那就用tag不就完了？）为了清晰化接口，使用方式应该是分组>tag>value，即首先用分组分隔，然后使用tag属性，value属性最好就不再使用了。
@ApiOperation
加在API的每个路径映射方法上（即真正的API接口）。value属性是必须的，描述该接口的内容，可以是中文。
response和responseContainer是两个重要的属性。前者表示返回的类，典型的Model.class，注意不是字符串，IDEA是可以解析的（Swagger体系内自动的做成一种Reference）；后者可选值为："List"，"Set"或者"Map"，注意是字符串。
@ApiImplicitParam & @ApiImplicitParams
加在API的参数上，最重要的注解之一。另有一个@ApiParam，是加在函数签名里面，不推荐，这两个是在函数签名的外面，更清晰。后者是前者的集合，比较简单，就不赘述了。前者比较重要的属性有
- name：和参数变量名保持一致；
- value：对这个参数的简要描述；
- required：是否必须；
- dataType：数据类型，注意原生类型（包装类也用原生的表示，例如Integer写"int"）都是小写，包括"string"；
- paramType：参数类型，"body"是普通参数，"path"是路径上的那种参数，"query"是url中问号的那种参数；
- allowableValues：参数允许的值，这个属性对自动化测试比较重要，具体参考JavaDoc，实际使用中最好写明。需要说明的是，在paramType为body时，range的设置是不生效的（原因未知）。
@ApiModel
以下两个注解都是加在Model里，便于在文档中对自定义类做详细的说明。这个注解加在Model类上。value属性可以提供一个名字，在文档中，会替换原来model的类名（没有试中文是否可行）。同时提供对超类和子类的描述，非字符串，便于生成继承关系（感觉这个功能可以通过代码分析实现）
@ApiModelProperty
加在Model的属性上，对属性做进一步描述和限定。同时这个注解可以加在getXXX方法上，如果XXX属性上也有，则以属性上的注解描述为准。考虑提供方法上加注解，可能是方便描述超类中的这个字段吧（protected类型）。该注解使用方式和@ApiImplicitParam类似。
由于引入了spring-boot-starter-swagger，可以直接支持JSR-303校验类的注解，包括@Pattern、@Max、@Min、@Size等。感觉Pattern是无法用@ApiModelProperty的属性替代的，其他好像都可以，说的不对还请作者指正。
