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;
