Swagger简介
产生
前后端集成，前端或者后端无法做到“及时协商，尽早解决”，最终导致问题集中爆发，Swagger可以实时跟踪最新的API，降低继承风险
特点
- 号称世界上最流行的API框架
- Restful Api 文档在线自动生成器 => API 文档 与API 定义同步更新
- 直接运行，在线测试API
- 支持多种语言 （如：Java，PHP等）
- 官网：swagger.io/
SpringBoot集成Swagger
- 创建SpringBoot-web项目
- 添加集成Swagger所需要的依赖
<!-- springboot集成swagger所需要用到的依赖 -->
<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>3.0.0</version>
</dependency>
<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>3.0.0</version>
</dependency>
如果导入的版本的3.0.0及以上的，需要多添加一个下面这个依赖
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-boot-starter</artifactId>
<version>3.0.0</version>
</dependency>
- 编写Swagger的配置类
SwaggerConfig来配置Swagger
@Configuration //配置类
@EnableSwagger2// 开启Swagger2的自动配置
public class SwaggerConfig {
}
-
- 如果导入的依赖是3.0.0一下的，直接通过http://localhost:8080/swagger-ui.html 访问
- 如果是3.0.0版本的，还要去主启动类添加
@EnableOpenApi注解，然后通过http://localhost:8080/swagger-ui/index.html 访问
主启动类
package com.example;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import springfox.documentation.oas.annotations.EnableOpenApi;
@EnableOpenApi
@SpringBootApplication
public class Springboot09SwaggerApplication {
public static void main(String[] args) {
SpringApplication.run(Springboot09SwaggerApplication.class, args);
}
}
- 访问结果：
配置Swagger（在SwaggerConfig中配置）
- 创建
Docket实例来配置Swagger - 通过
apiInfo()属性配置文档信息 - Docket实例关联apiInfo()来配置Swagger的界面信息。
package com.example.config;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
import java.util.ArrayList;
@Configuration //标注这是一个配置类
@EnableSwagger2 //开启Swagger2自动配置
public class SwaggerConfig {
//配置Swagger：Swagger实例Bean是Docket，所以通过配置Docket实例来配置Swagger。
@Bean
public Docket docket(){//配置docket来配置Swagger的具体参数
return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo());//关联apiInfo()
}
//配置文档信息
private ApiInfo apiInfo(){
Contact contact = new Contact("作者博客", "https://juejin.cn/user/703307009491261", "suisuinian@qq.com");
return new ApiInfo(
"这就是简单的Swagger。。。。",//标题
"这个东西还不错，挺好用的",//描述
"v10.0+",//版本
"https://juejin.cn/user/703307009491261",//组织链接
contact,//联系人信息
"Apach许可",//许可
"https://www.apache.org/",//许可链接
new ArrayList<>()//扩展
);
}
}
- 运行结果：
- 对比，看看配置文档信息对应修改的内容
配置扫描接口
通过select()方法配置怎么扫描接口。
@Bean
public Docket docket(){//配置docket来配置Swagger的具体参数
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())//关联apiInfo()
.select()//通过select()方法扫描接口
//RequestHandlerSelectors.basePackage根据包扫描，常用的一种形式
.apis(RequestHandlerSelectors.basePackage("com.example.controller"))
.build()
;
}
扫描接口的方式
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) // 根据包路径扫描接口
除了这些，我们还可以通过paths()配置接口扫描过滤
@Bean
public Docket docket(){//配置docket来配置Swagger的具体参数
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())//关联apiInfo()
.select()//通过select()方法扫描接口
//RequestHandlerSelectors.basePackage根据包扫描，常用的一种形式
.apis(RequestHandlerSelectors.basePackage("com.example.controller"))
// 配置如何通过path过滤,即这里(扫描和过滤)了以/example开头的接口
.paths(PathSelectors.ant("/example/**"))
.build()
;
}
过滤的方式
配置Swagger的开关
通过enable()方法配置Swagger的开关，默认是true
@Bean
public Docket docket(){//配置docket来配置Swagger的具体参数
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())//关联apiInfo()
.enable(false) //配置是否启用Swagger，如果是false，在浏览器将无法访问
.select()//通过select()方法扫描接口
//RequestHandlerSelectors.basePackage根据包扫描，常用的一种形式
.apis(RequestHandlerSelectors.basePackage("com.example.controller"))
// 配置如何通过path过滤,即这里只扫描请求以/example开头的接口
.paths(PathSelectors.ant("example/**"))
.build()
;
}
结果：
- 可以用来动态设置项目环境不同时的Swagger不同的开关情况
配置API分组
默认是没用配置分组的，只有一个默认的default
我们可以通过groupName() 来配置分组
@Bean
public Docket docket(){//配置docket来配置Swagger的具体参数
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())//关联apiInfo()
.groupName("group")
.enable(true) //配置是否启用Swagger，如果是false，在浏览器将无法访问
.select()//通过select()方法扫描接口
//RequestHandlerSelectors.basePackage根据包扫描，常用的一种形式
.apis(RequestHandlerSelectors.basePackage("com.example.controller"))
// 配置如何通过path过滤,即这里只扫描请求以/example开头的接口
.paths(PathSelectors.ant("example/**"))
.build()
;
}
结果：
- 我们还可以通过创建多个
docket来配置多个分组
@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");
}
配置实体类
- 创建实体类
- 在实体类上添加注解信息
package com.example.pojo;
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
@ApiModel("用户实体")
public class User {
@ApiModelProperty("用户id")
public int id;//一定要是public属性，private属性扫描不到
@ApiModelProperty("用户姓名")
public String name;
}
- 在controller层编写返回视图
- 只要这个实体在请求接口的返回值上（即使是泛型），都能映射到实体项中：
package com.example.controlller;
import com.example.pojo.User;
import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;
@RestController
public class HelloController {
@PostMapping(value = "/user")
public User getUser(){
return new User();
}
}
其中
- @ApiModel为类添加注释
- @ApiModelProperty为类属性添加注释
- 结果：
