01.Swagger2

1,引入Swagger2相关依赖

<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>
<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.9.2</version>
</dependency>

2,启动Swagger2

//在主启动文件中增加@EnableSwagger2即可
/**
 * @EnableSwagger2 是springfox提供的一个注解
 * 待办swagger2相关技术开启,会扫描当前类所在包及子包中所有的类型的注解,做swagger2文档的定制
 * @author VainGlory
 *
 */
@SpringBootApplication
@EnableSwagger2
public class SwaggerTestApplication {

	public static void main(String[] args) {
		SpringApplication.run(SwaggerTestApplication.class, args);
	}

}

3,启动后的访问地址

http://localhost:8080/swagger-ui.html#/

4,Swagger的基本配置

//增加一个config配置类,
添加@Configuration注解
加入spring容器@Bean

package com.serlyf.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

import com.google.common.base.Predicates;
import com.serlyf.anno.MyAnnotation4Swagger;

import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;

@Configuration
public class SwaggerConfiguration {

	/**
	 * 创建Docket类型的对象,并使用Spring的容器管理,Docket是Swagger中的全局配置对象
	 * @return
	 */
	@Bean
	public Docket docket(){
		Docket docket =new Docket(DocumentationType.SWAGGER_2);
		
		/**
		 * ApiInfo api 帮助文档的信息
		 */
		ApiInfo apiInfo=new ApiInfoBuilder()
				.contact(new Contact("serlfy", "com.serlfy", "aaa.qq.com"))
				.title("swagger框架学习文档")
				.description("描述信息")
				.version("1.0")
				.build();
		
		docket.apiInfo(apiInfo);
		
		docket=docket
			.select() //获取Docket中的选择器,返回ApiSelectBuilder,构建选择器的,比如,扫描什么包的注解
			//1,基本不需要配置
			.apis(Predicates.not(
                              //取反
                              RequestHandlerSelectors.withMethodAnnotation(
                              //当方法上有XXX注解的时候返回true
			      MyAnnotation4Swagger.class)
					))
			//2,基本不需要配置
			.apis(RequestHandlerSelectors.basePackage("com.serlfy.controller"))//设定扫描哪个包(包括子包)中的注解
			.paths(Predicates.or(PathSelectors.regex("/swagger/.*"),PathSelectors.regex("/swagger2/.*"),PathSelectors.regex("/.*")))//使用正则表达式,约束生产API文档的路径地址,比如只有匹配路径为/swagger的才生成API文档
			.build();
		
		return docket;
	}
}

5,自定义注解及使用

package com.serlyf.anno;

import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;

/**
 * @Target--描述当前的注解可以定义在什么资源上
 * 	属性-value
 * 		-定义具体的资源,包括:
 * 		ElementType.METHOD:可以定义在方法上
 * 		ElementType.TYPE :可以定义在类型上
 * 		ElementType.FIELD: 可以定义在属性上
 * 		ElementType.PARAMETER:可以定义到方法参数上
 * @Retention:-当前注解在什么时候生效
 * 	属性-value
 * 		定义具体的生效标记:
 * 		RetentionPolicy.RUNTIME --运行时生效
 * 		RetentionPolicy.SOURCE --源码时生效
 * 		RetentionPolicy.CLASS --字节码时生效
 * 		
 * 
 * @author VainGlory
 *
 */
@Target(value={ElementType.METHOD,ElementType.TYPE})
@Retention(RetentionPolicy.RUNTIME)
public @interface MyAnnotation4Swagger {
	
	//自定义注解中的属性,相当于@MyAnnotation4Swagger(value="")
	String value() default "";
}

//自定义注解的使用见上文基本配置文件中的配置

6,Swagger生成API文档的范围

.paths(Predicates.or(PathSelectors.regex("/swagger/.*"),PathSelectors.regex("/swagger2/.*"),PathSelectors.regex("/.*")))//使用正则表达式,约束生产API文档的路径地址,比如只有匹配路径为/swagger的才生成API文档

7,常用注解

1,类注解:@Api(tags={"MyController","Swagger学习"})给当前控制器增加标签
2,方法注解:@ApiOperation(value="get请求,获取数据...")
3,参数注解:@ApiParam(name="用户名",value="传入参数",required=true)String name
4,@ApiIgnore //忽略当前注解描述的方法或者类型不生成API帮助文档
5,方法上的参数描述:@ApiImplicitParam(name="name", value="name的描述",required=false,paramType="字符串")
6,方法上的参数描述数组:@ApiImplicitParams(value={@ApiImplicitParam(name="name", value="name的描述",required=false,paramType="字符串"),})

8,实体类注解

/**
 * @ApiModel 描述一个实体类型,这个实体类型如果成为任何一个生成API文档方法的返回值类型的时候,此注解被解析
 * @author VainGlory
 *
 */
@ApiModel(value="自定义实体",description="存储用户数据")
public class MyEntity {

	@ApiModelProperty(value="主键",name="主键(ID)",required=false,example="1111",hidden=false)
	private String id;
	@ApiModelProperty(value="姓名",name="姓名(name)",required=false,example="张三",hidden=false)
	private String name;
	@ApiModelProperty(value="密码",name="密码(password)",required=false,example="123456",hidden=false)
	private String password;