1. 了解目的
- Swagger的概念及作用
- 项目中集成Swagger自动生成API文档
2. Swagger概要
前后端分离相对独立且松耦合,导致前后端通过API进行交互。
Restful API 文档在线生成器,API文档和API定义同步更新。
作用:解决前后端分离产生的问题--无法及时的沟通进行处理问题,Swagger可以实时地更新API。
优点:
- 文档在线自动生成
- 直接运行,在线进行测试
- 支持多种语言
官网:API Documentation & Design Tools for Teams | Swagger
3. SpringBoot集成Swagger
前提:JDK的版本需要达到1.8以上。
需要引入依赖的包:
<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>
集成Swagger
- 新建SpringBoot Web项目
- 添加集成Swagger的依赖
- 编写控制类,进行测试
- 配置Swagger--配置类SwaggerConfig
@Configuration //配置类
@EnableSwagger2 //开启Swagger2的自动配置
public class SwaggerConfig {
}
启动工程,访问:http://localhost:8080/swagger-ui.html,即可看到Swagger的界面。
配置Swagger
1. 通过Swagger的实例Docket来配置Swagger
@Bean //配置docket以配置Swagger具体参数
public Docket docket() {
return new Docket(DocumentationType.SWAGGER_2);
}
2. 可以通过apiInfo()来配置文档的信息
//配置文档信息
private ApiInfo apiInfo() {
Contact contact = new Contact("名字", "访问链接", "邮箱");
return new ApiInfo(
"Swagger学习", // 标题
"学习演示如何配置Swagger", // 描述
"v1.0", // 版本
"http://terms.service.url/组织链接", // 组织链接
contact, // 联系人信息
"Apach 2.0 许可", // 许可
"许可链接", // 许可连接
new ArrayList<>()// 扩展
);
}
3. 在Docket上关联apiInfo()
@Bean
public Docket docket() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo());
}
4. 重启项目,查看Swagger展示效果
配置扫描接口
1. 构建Docket时通过select()方法来配置要扫描的接口
@Bean
public Docket docket() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select() //通过.select()方法,去配置扫描接口
//RequestHandlerSelectors配置如何扫描接口
.apis(RequestHandlerSelectors.basePackage("com.nanshan.swagger.controller"))
.build();
}
2. 重启项目,可以观察到根据包路径扫描接口,可以看到自定义的类
3. 扫描接口的配置
// 扫描所有,项目中的所有接口都会被扫描到
any()
// 不扫描接口
none()
// 通过方法上的注解扫描,如.withMethodAnnotation(GetMapping.class)只扫描get请求
withMethodAnnotation(final Class<? extends Annotation> annotation)
// 通过类上的注解扫描,如.withClassAnnotation(Controller.class)只扫描有controller注解的类中的接口
withClassAnnotation(final Class<? extends Annotation> annotation)
// 根据包路径扫描接口
basePackage(final String basePackage)
配置过滤扫描
@Bean
public Docket docket() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
// 通过.select()方法,去配置扫描接口,RequestHandlerSelectors配置如何扫描接口
.select()
.apis(RequestHandlerSelectors.basePackage("com.nanshan.swagger.controller"))
// 配置如何通过path过滤,即这里只扫描请求以/kuang开头的接口
.paths(PathSelectors.ant("/nanshan/**"))
.build();
}
过滤值的选择:
// 任何请求都扫描
any()
// 任何请求都不扫描
none()
// 通过正则表达式控制
regex(final String pathRegex)
// 通过ant()控制
ant(final String antPattern)
配置开关Swagger
1. 通过enable()方法配置是否启用swagger,如果是false,swagger将不能在浏览器中访问了
@Bean
public Docket docket() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
//配置是否启用Swagger,如果是false,在浏览器将无法访问
.enable(false)
.select()// 通过.select()方法,去配置扫描接口,RequestHandlerSelectors配置如何扫描接口
.apis(RequestHandlerSelectors.basePackage("com.nanshan.swagger.controller"))
// 配置如何通过path过滤,即这里只扫描请求以/kuang开头的接口
.paths(PathSelectors.ant("/nanshan/**"))
.build();
}
2. 如何动态配置当项目处于test、dev环境时显示swagger,处于prod时不显示?
@Bean
public Docket docket(Environment environment) {
// 设置要显示swagger的环境
Profiles of = Profiles.of("dev", "test");
// 判断当前是否处于该环境
// 通过 enable() 接收此参数判断是否要显示
boolean b = environment.acceptsProfiles(of);
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.enable(b) //配置是否启用Swagger,如果是false,在浏览器将无法访问
.select()// 通过.select()方法,去配置扫描接口,RequestHandlerSelectors配置如何扫描接口
.apis(RequestHandlerSelectors.basePackage("com.nanshan.swagger.controller"))
// 配置如何通过path过滤,即这里只扫描请求以/kuang开头的接口
.paths(PathSelectors.ant("/nanshan/**"))
.build();
}
增加配置文件:
application.properties、application-dev.properties、application-pro.properties
# 激活对应的生产环境
spring.profiles.active=dev
server.port=8081
server.port=8082
配置分组
1. 如果没有配置分组,默认是default。通过groupName()方法即可配置分组
@Bean
public Docket docket(Environment environment) {
return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo())
.groupName("nanshan") // 配置分组
// 省略配置....
}
2. 配置多个分组
@Bean
public Docket docket1(){
return new Docket(DocumentationType.SWAGGER_2).groupName("group1");
}
@Bean
public Docket docket2(){
return new Docket(DocumentationType.SWAGGER_2).groupName("group2");
}
@Bean
public Docket docket3(){
return new Docket(DocumentationType.SWAGGER_2).groupName("group3");
}
3. 重启项目查看分组
配置实体类
1. 实体类
@ApiModel("用户实体")
public class User {
@ApiModelProperty("用户名")
public String username;
@ApiModelProperty("密码")
public String password;
}
2. 只要这个实体在请求接口的返回值上(即使是泛型),都能映射到实体中
@RequestMapping("/getUser")
public User getUser(){
return new User();
}
3. 重启查看项目
注:并不是因为@ApiModel这个注解让实体显示在这里了,而是只要出现在接口方法的返回值上的实体都会显示在这里,而@ApiModel和@ApiModelProperty这两个注解只是为实体添加注释的。
@ApiModel为类添加注释
@ApiModelProperty为类属性添加注释
请求接口的配置
@ApiOperation("南山的接口")
@PostMapping("/nanshan")
@ResponseBody
public String nanshan(@ApiParam("这个名字会被返回")String username){
return username;
}
注意:
在正式环境要记得关闭Swagger,一来出于安全考虑二来也可以节省运行时内存。