想完全掌握Swagger,这一篇就够了！
Swagger
- 一、Swagger基础
- 二、SpringBoot集成swagger
- 三、配置Swagger信息
-
- 3.1 配置Swagger信息的ApiInfo
- 3.2 Swagger配置扫描接口
- 3.3 配置Swagger是否启动
- 3.4 配置Api文档的分组
- 3.5 配置Api文档的注解
一、Swagger基础
swagger：
号称世界上最流行的Api框架
RestFul Api文档在线自动生成工具=>Api文档与Api定义同步更新
直接运行，可以在线测试Api接口
支持多种语言，java php
二、SpringBoot集成swagger
1、新建一个spring项目
2、修改maven仓库
3、导入依赖
io.springfox
springfox-swagger2
2.9.2
io.springfox
springfox-swagger-ui
2.9.2
4、编写一个Hello工程
import org.springframework.web.bind.annotation.RestController;
/**
* @author potential
*/
@RestController
public class HelloController {
/**
* 每个项目都会有一个默认的请求 /error
*/
@RequestMapping(value="/hello")
public String hello(){
return "hello";
}
5、配置swagger
创建SwaggerConfig类，添加如下内容
package com.kuang.swagger.config;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
/**
*SwaggerConfig 一定是要配置到springboot里面
* 所以需要添加@Configuration注解
* @author potential
*/
@Configuration
@EnableSwagger2 //开启swagger2
public class SwaggerConfig {
}
6、测试
启动，主启动类，进入http://localhost:8080/swagger-ui.html，查看swagger的web界面，呈现下面页面，即表示集成成功。
三、配置Swagger信息
Swagger的bean实例Docket：
在SwaggerConfig类中，添加如下内容，表示已经将Swagger的bean实例Docket实例化
/**
* 配置swagger的Docket的Bean实例
*/
@Bean
public Docket docket(){
return new Docket(DocumentationType.SWAGGER_2);
3.1 配置Swagger信息的ApiInfo
1、在SwaggerConfig类中，添加如下内容，设置ApiInfo信息，并且将其在实例化的Docket中调用
/**
*SwaggerConfig 一定是要配置到springboot里面
* 所以需要添加@Configuration注解
* @author potential
*/
@Configuration
@EnableSwagger2 //开启swagger2
public class SwaggerConfig {
/**
* 配置swagger的Docket的Bean实例
*/
@Bean
public Docket docket(){
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo());
}
/**
* 配置Swagger信息的apiInfo
*/
private ApiInfo apiInfo(){
//作者信息
Contact contact = new Contact("李","https://blog.csdn.net/wangzhihao1994/article/details/108408420","[email protected]");
return new ApiInfo(
"狂神的Swagger日记",
"即使再小的帆也能远航",
"1.0",
"https://blog.csdn.net/wangzhihao1994/article/details/108408420",
contact,
"Apache 2.0",
"http://www.apache.org/licenses/LICENSE-2.0",
new ArrayList());
}
2、运行，查询结果
3.2 Swagger配置扫描接口
2、在SwaggerConfig类的方法docket中，添加如下内容，配置扫描接口，具体属性如下代码中的解释。
/**
* 配置swagger的Docket的Bean实例
*/
@Bean
public Docket docket(){
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
/*
配置要扫描的接口的方式
basePackage:指定要扫描的包
any()：扫描全部
none()：都不扫描
withClassAnnotation：扫描类上的注解，参数是一个注解的反射
withMethodAnnotation:扫描方法上的注解
例如：.apis(RequestHandlerSelectors.withMethodAnnotation(RestController.class))
只会去扫描类上的RestController的这些类
*/
.apis(RequestHandlerSelectors.basePackage("com.kuang.swagger.controller"))
//过滤什么路径 相当于只扫描带有Kuang下面的请求
.paths(PathSelectors.ant("/kuang/**"))
.build();
}
3.3 配置Swagger是否启动
enable()；控制swagger是否启动
若为false，则不可启动 swagger的ui界面会提示
若为true，则可以启动
相关面试题：
我只希望我的swagger在生产环境中使用，在发布的时候不适用？
思路：1、判断是不是生产环境 flag=false
2、注入enable(flag)
解答：
1、模拟多环境配置
其中application.properties里面添加如下内容：
#激活dev环境
spring.profiles.active=dev
application-dev.properties添加如下内容：
server.port=8081
application-pro.properties添加如下内容：
server.port=8082
2、将SwaggerConfig类中的内容修改为下面内容
/**
*SwaggerConfig 一定是要配置到springboot里面
* 所以需要添加@Configuration注解
* @author potential
*/
@Configuration
@EnableSwagger2 //开启swagger2
public class SwaggerConfig {
/**
* 配置swagger的Docket的Bean实例
*/
@Bean
public Docket docket(Environment environment){
//设置要显示的swagger环境
Profiles profiles=Profiles.of("dev");
/*
获取项目的环境
通过environment.acceptsProfiles()来判断是否在自己设定的环境当中
*/
boolean flag = environment.acceptsProfiles(profiles);
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.enable(flag)
.select()
/*
配置要扫描的接口的方式
basePackage:指定要扫描的包
any()：扫描全部
none()：都不扫描
withClassAnnotation：扫描类上的注解，参数是一个注解的反射
withMethodAnnotation:扫描方法上的注解
例如：.apis(RequestHandlerSelectors.withMethodAnnotation(RestController.class))
只会去扫描类上的RestController的这些类
*/
.apis(RequestHandlerSelectors.basePackage("com.kuang.swagger.controller"))
//过滤什么路径 相当于只扫描带有Kuang下面的请求
.paths(PathSelectors.ant("/kuang/**"))
.build();
}
/**
* 配置Swagger信息的apiInfo
*/
private ApiInfo apiInfo(){
//作者信息
Contact contact = new Contact("李","https://blog.csdn.net/wangzhihao1994/article/details/108408420","[email protected]");
return new ApiInfo(
"狂神的Swagger日记",
"即使再小的帆也能远航",
"1.0",
"https://blog.csdn.net/wangzhihao1994/article/details/108408420",
contact,
"Apache 2.0",
"http://www.apache.org/licenses/LICENSE-2.0",
new ArrayList());
}
}
测试结果：
3.4 配置Api文档的分组
在SwaggerConfig类的Docket类中添加如下内容：
.groupName("狂神")
相关题目
如何配置多个组
添加多个Docket实例即可
在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");
}
测试：
3.5 配置Api文档的注解
在controller中加入注解
测试
注意：
在这里，在controller中加入的注解不要与pojo中加入的注解弄混淆了
在pojo中如果想加入注释信息使用的注解如下面所示：
