Swagger和Postman

1.postman的优点

是可以保存你之前输入过的参数，每次只要打开点一下测试就行了。

2. 写完了swagger之后一键导入postman

（1） swagger正常写，写完了之后打开swagger页面，然后右键审查元素（这里试过，用源代码确实找不到）

打开了之后，搜api-docs，把前面的那个网址复制一下。
粘贴这个网址的技巧，把这个网址打开，然后从地址栏里面粘贴。

（2） 导入Postman
点import，然后import from link，把网址粘进去，over。

3. swagger-starter整合swagger

swagger-starter的优点

1. 引入足够简单，只需要2步（如果有Shiro就是3步）
2. 方便的Swagger开关
3. 支持yaml格式的配置
4. 支持API的分组显示（在API过多的情况下非常好用）

（简易版本的引入）

（1） 导入pom文件

        <dependency>
            <groupId>io.github.wilson-he</groupId>
            <artifactId>swagger2-spring-boot-starter</artifactId>
            <version>1.0.3.RELEASE</version>
        </dependency>

（2）yml添一句

swagger:
  enabled: true

---

（正常版本的引入）

引入过程：

1. pom文件引入

        <dependency>
            <groupId>com.spring4all</groupId>
            <artifactId>spring-boot-starter-swagger</artifactId>
            <version>1.5.1.RELEASE</version>
        </dependency>

2. 主文件加Annotation（其实到这一步就已经可以了，已经可以访问网页）

@SpringBootApplication
@EnableSwagger2Doc
public calss TestSwaggerApplication{

以及这里的@Enable可以改成yml里面的enable

3. 配置文件
   配置文件统一放到了项目的application.yml中，稍后计划使用新的文件，并采用引入的方式实现配置文件的分离

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. 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，是加在函数签名里面，不推荐，这两个是在函数签名的外面，更清晰。后者是前者的集合，比较简单，就不赘述了。前者比较重要的属性有

1. name：和参数变量名保持一致；
2. value：对这个参数的简要描述；
3. required：是否必须；
4. dataType：数据类型，注意原生类型（包装类也用原生的表示，例如Integer写"int"）都是小写，包括"string"；
5. paramType：参数类型，"body"是普通参数，"path"是路径上的那种参数，"query"是url中问号的那种参数；
6. 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的属性替代的，其他好像都可以，说的不对还请作者指正。