SpringBoot集成Swagger
1、什么是Swagger
1、编写完Controller后生成接口文档,可以加上有相关的提示信息
2、可以在线测试接口
3、接口文档随着开发的进行实时更新
2、准备工作
1、新建一个SpringBoot项目,勾选上Spring Web
2、导入相关依赖
<!-- 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>
<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.2</version>
</dependency>
3、编写Controller
@RestController
public class HelloController {
@GetMapping("/hello")
public String hello(){
return "hello~";
}
@PostMapping("/login")
public User login(String name, String pwd){
return new User(name, pwd);
}
}
4、配置Swagger
@Configuration
@EnableSwagger2
public class SwaggerConfig {
}
5、测试运行
访问http://localhost:8080/swagger-ui.html,会跳转到以下页面
该页面在导入的包中,这是Swagger提供给我们进行接口测试的页面
3、配置Swagger
1、将Swagger的bean实例docket加入到Spring容器
@Configuration
@EnableSwagger2
public class SwaggerConfig {
@Bean
public Docket docket(){
return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo());
}
private ApiInfo apiInfo(){
Contact contact = new Contact("Rengar", "https://www.csdn.net/", "1257341673@qq.com");
return new ApiInfo("Rengar的SwaggerAPI文档",//标题
"Api Documentation",//描述
"V1.0",
"https://www.csdn.net/",//术语服务连接
contact,
"Apache 2.0",
"http://www.apache.org/licenses/LICENSE-2.0",
new ArrayList());
}
}
2、访问http://localhost:8080/swagger-ui.html,会发现该页面的一些信息发生了改变
以上的代码配置对应图中的一些信息
4、配置扫描接口及开关
1、自定义扫描接口的范围
默认情况下是扫描所有接口
以下代码自己自定义扫描的范围
@Configuration
@EnableSwagger2
public class SwaggerConfig {
@Bean
public Docket docket(){
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
//.enable(false)关闭这个功能(页面)
.select()
//basePackage("com.rengar.controller") 扫描com.rengar.controller这个包
//any() 扫描所有接口
//none() 全部不扫描
//withClassAnnotation(RestController.class) 扫描类上带有RestController的所有接口
//withMethodAnnotation(RequestMapping.class) 扫描类上带有RequestMapping的所有接口
.apis(RequestHandlerSelectors.basePackage("com.rengar.controller"))
//将路径以/rengar/开头的所有API写入接口文档
//.paths(PathSelectors.ant("/rengar/**"))
.build();
}
private ApiInfo apiInfo(){
Contact contact = new Contact("Rengar", "https://www.csdn.net/", "1257341673@qq.com");
return new ApiInfo("Rengar的SwaggerAPI文档",//标题
"Api Documentation",//描述
"V1.0",
"https://www.csdn.net/",//术语服务连接
contact,
"Apache 2.0",
"http://www.apache.org/licenses/LICENSE-2.0",
new ArrayList());
}
}
2、让Swagger只在开发环境中使用
如何让Swagger在开发环境下使用,上线是不使用?
1、创建多个环境配置
2、在配置类中指定Swagger显示的环境
@Configuration
@EnableSwagger2
public class SwaggerConfig {
@Bean
public Docket docket(Environment environment){
//设置要显示的Swagger环境 只在dev和test环境中显示
Profiles profiles = Profiles.of("dev", "test");
//判断是否在自己设定的环境中
boolean flag = environment.acceptsProfiles(profiles);
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.enable(flag)//关闭这个功能(页面)
.select()
//basePackage("com.rengar.controller") 扫描com.rengar.controller这个包
//any() 扫描所有
//none() 全部不扫描
//withClassAnnotation(RestController.class) 扫描类上带有RestController的所有
//withMethodAnnotation(RequestMapping.class) 扫描类上带有RequestMapping的所有
.apis(RequestHandlerSelectors.basePackage("com.rengar.controller"))
//拦截这个请求 /rengar/下的所有请求
//.paths(PathSelectors.ant("/rengar/**"))
.build();
}
private ApiInfo apiInfo(){
Contact contact = new Contact("Rengar", "https://www.csdn.net/", "1257341673@qq.com");
return new ApiInfo("Rengar的SwaggerAPI文档",//标题
"Api Documentation",//描述
"V1.0",
"https://www.csdn.net/",//术语服务连接
contact,
"Apache 2.0",
"http://www.apache.org/licenses/LICENSE-2.0",
new ArrayList());
}
}
5、配置API分组
在容器里放入多个Docket,每个Docket设置一个唯一的groupName
@Configuration
@EnableSwagger2
public class SwaggerConfig {
@Bean
public Docket docket1(){
return new Docket(DocumentationType.SWAGGER_2).groupName("A");
}
@Bean
public Docket docket2(){
return new Docket(DocumentationType.SWAGGER_2).groupName("B");
}
@Bean
public Docket docket3(){
return new Docket(DocumentationType.SWAGGER_2).groupName("C");
}
@Bean
public Docket docket(Environment environment){
//设置要显示的Swagger环境 只在dev和test环境中显示
Profiles profiles = Profiles.of("dev", "test");
//判断是否在自己设定的环境中
boolean flag = environment.acceptsProfiles(profiles);
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.enable(flag)//关闭这个功能(页面)
.groupName("Rengar")
.select()
//basePackage("com.rengar.controller") 扫描com.rengar.controller这个包
//any() 扫描所有
//none() 全部不扫描
//withClassAnnotation(RestController.class) 扫描类上带有RestController的所有
//withMethodAnnotation(RequestMapping.class) 扫描类上带有RequestMapping的所有
.apis(RequestHandlerSelectors.basePackage("com.rengar.controller"))
//拦截这个请求 /rengar/下的所有请求
//.paths(PathSelectors.ant("/rengar/**"))
.build();
}
private ApiInfo apiInfo(){
Contact contact = new Contact("Rengar", "https://www.baidu.com/", "1257341673@qq.com");
return new ApiInfo("Rengar的SwaggerAPI文档",//标题
"Api Documentation",//描述
"V1.0",
"https://www.baidu.com/",//术语服务连接
contact,
"Apache 2.0",
"http://www.apache.org/licenses/LICENSE-2.0",
new ArrayList());
}
}
分组后的效果
6、Model和接口文档的提示信息
1、在实体类加注解,让实体类也在swagger-ui.html页面的Model部分出现,并写上提示信息
(接口文档是给其他人看的,加上实体类和提示信息,方便阅读)
@ApiModel("用户实体类")
//将实体类加入到Swagger中,并标注为"用户实体类"
public class User {
@ApiModelProperty("用户名")
//该属性标注为"用户名"
private String name;
@ApiModelProperty("密码")
//该属性标注为"密码"
private String pwd;
public User() {
}
public User(String name, String pwd) {
this.name = name;
this.pwd = pwd;
}
public String getName() {
return name;
}
public void setName(String name) {
this.name = name;
}
public String getPwd() {
return pwd;
}
public void setPwd(String pwd) {
this.pwd = pwd;
}
}
2、接口上也可以写相关的提示信息
@Api(tags = "Hello控制器")
@RestController
public class HelloController {
@GetMapping("/hello")
@ApiOperation("欢迎请求")
public String hello(){
return "hello~";
}
@PostMapping("/login")
@ApiOperation("登录请求")
//@ApiParam("用户名")给参数加上提示信息的时候,会使Swagger无法正常测试该接口
public User login(String name, String pwd){
return new User(name, pwd);
}
}
在参数上加入提示信息会使该接口无法正常测试
测试接口时,先把@ApiParam("")(参数上的注释)删掉
7、利用Swagger测试接口
在线测试接口,输入数据(图中的name和pwd),查看放回的json(图中的Response body)