spring boot ＋Swagger-ui 自动生成API文档

一、spingboot整合swagger-ui
1、导包：

      <dependency>
			<groupId>io.springfox</groupId>
			<artifactId>springfox-swagger2</artifactId>
			<version>2.9.2</version>
		</dependency>
		<dependency>
			<groupId>io.springfox</groupId>
			<artifactId>springfox-swagger-ui</artifactId>
			<version>2.9.2</version>
		</dependency>
		<dependency>
			<groupId>io.springfox</groupId>
			<artifactId>springfox-bean-validators</artifactId>
			<version>2.9.2</version>
		</dependency>

2、添加SwaggerConfig类：

@Profile("local") 
@Configuration
@EnableSwagger2
public class SwaggerConfig {

/*通过此属性，在springboot的配置文件中控制api文档是否可用*/
    @Value("${debug}")
    private boolean debug;

    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.test"))
                .paths(PathSelectors.any())
                .build()
                .enable(debug);
    }
}

上述的basePackage中填写需要生成api文档的文件夹。

二、使用
直接以注解的形式使用，具体用法如下：

• @Api()用于类；
  表示标识这个类是swagger的资源，一般用在controller类上；
  常用的属性有：
  tags–表示说明，可用于标注该接口类的作用
  value–也是说明，可以使用tags替代
  description-描述，可以是长文本，但从1.5.X版本之后就已废弃
• @ApiOperation()用于方法；
  表示一个http请求的操作，一般用在controller类中的方法上；
  常用属性有：
  value用于方法描述
  notes用于提示内容
  tags可以重新分组（视情况而用）
• @ApiParam()用于方法，参数，字段说明；
  表示对参数的添加元数据（说明或是否必填等），一般用在controller类中接收请求的参数前；
  常用属性有：
  name–参数名
  value–参数说明，默认可省略value，直接写参数说明
  required–是否必填，true为必填
• @ApiModel()用于实体类
  表示对类进行说明，用于参数用实体类接收；
  常用属性有：
  value–表示对象名
  description–描述
• @ApiModelProperty()用于实体类中的方法，字段
  表示对model属性的说明或者数据操作更改；
  常用属性有：
  value–字段说明
  name–重写属性名字
  dataType–重写属性类型
  required–是否必填
  example–举例说明
  hidden–隐藏
  三、注意事项
  此处划重点，由于是刚接触swagger-ui，所以在使用时，有很多没有注意到的地方，因此，无意中踩了一个坑。
  在使用@ApiModel注解时，由于没弄清楚其属性的具体作用，直接在Test1实体类上写了@ApiModel（“测试类”），并且此时，给Test2实体类也如此定义：@ApiModel（“测试类”）。导致在接口文档中查看时，发现这两个类的属性同时出现在了同一个Model中。
  本应当是两个Model，而合并为了一个Model，为此，笔者还花费了好大一会才弄明白，本来以为是swagger-ui出Bug了。哈哈哈。。。
  后来经过分析，发现@ApiModel注解与其他几个注解不同，当不写属性时，默认为value=“测试类”，而此注解中的value属性，是指该实体类的对象名。其他注解的velue属性才为类的说明。
  当两个类的对象名填写为一样时，swagger-ui认为这两个类是同一个类，于是两个类的属性进行了合并，就出现了笔者遇到的乌龙。
  对于@ApiModel，正确的使用方法应该为**@ApiModel(description = “测试类”)**，此时，即使两个类中填写了一样的说明，也不会出现上述类属性被合并的情形。