Swagger
号称世界上最流行的API框架
Restful Api 文档在线自动生成器 => API 文档 与API 定义同步更新
直接运行,在线测试API
支持多种语言 (如:Java,PHP等)
官网:https://swagger.io/
SpringBoot继承Swagger
- 创建springboot项目,导入依赖
<!--Swagger-->
<!-- 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>
- 创建一个配置类
@Configuration
@EnableSwagger2 //开启Swagger2自动配置
public class SwaggerConfig {
}
- 测试
打开http://localhost:8080/swagger-ui.html
配置Swagger
@Configuration
@EnableSwagger2 //开启Swagger2自动配置
public class SwaggerConfig {
// Swagger实例
@Bean
public Docket docket(@Qualifier("apiInfo") ApiInfo apiInfo) {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo);
}
@Bean
public ApiInfo apiInfo() {
// contact是作者信息
Contact contact = new Contact("wcy", "https://www.baidu.com", "836680474@qq.com");
return new ApiInfo(
"API文档", // 标题
"测试文档", // 描述
"1.0", // 版本号
"urn:tos", // 组织链接
contact, //作者信息
"Apache 2.0", // 许可
"https://www.apache.org/licenses/LICENSE-2.0", // 许可链接
new ArrayList()// 扩展
);
}
}
此时打开就是我们配置的信息
可以看到他扫描到了我们的控制器路由和默认的路由/error
他默认扫描了所有的接口
这个我们可以配置
配置扫描接口
- 通过apis()来指定
@Bean
public Docket docket(@Qualifier("apiInfo") ApiInfo apiInfo) {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo)
.select()
// 扫描指定包
.apis(RequestHandlerSelectors.basePackage("com.wcy.controller"))
.build();
}
在配置了指定的包后,只能扫描到我们自己的Controller
RequestHandlerSelectors还有如下几种配置
- any() 全部扫描
- none() 全部不扫描
- withClassAnnotation() 扫描类上的指定注解
// 类上的RestController注解
RequestHandlerSelectors.withMethodAnnotation(RestController.class)
- withMethodAnnotation() 扫描方法上指定注解
// 扫描方法上的GetMapping注解的路由
RequestHandlerSelectors.withMethodAnnotation(GetMapping.class)
- 通过paths()指定
此时的配置为先扫描RestController注解,然后在检查是否有/user/开头的请求
@Bean
public Docket docket(@Qualifier("apiInfo") ApiInfo apiInfo) {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo)
.select()
// 扫描指定包
.apis(RequestHandlerSelectors.withClassAnnotation(RestController.class))
// 指定扫描的路径
.paths(PathSelectors.ant("/user/**"))
.build();
}
PathSelectors也有可选项
- any() // 任何请求都扫描
- none() // 任何请求都不扫描
- regex(final String pathRegex) // 通过正则表达式控制
- ant(final String antPattern) // 路径
配置Swagger开关
是否启用swagger
- enable(true) 开
- enable(false) 关
// Swagger实例
@Bean
public Docket docket(@Qualifier("apiInfo") ApiInfo apiInfo) {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo)
// swagger开关
.enable(false)
.select()
// 扫描指定包
.apis(RequestHandlerSelectors.withClassAnnotation(RestController.class))
// 指定扫描的路径
.paths(PathSelectors.any())
.build();
}
设置为false时会为如下界面
特定环境启用Swagger
配置当项目处于test、dev环境时显示swagger,处于prod时不显示
// Swagger实例
@Bean
public Docket docket(
@Qualifier("apiInfo") ApiInfo apiInfo,
Environment environment) {
// 获取环境的配置文件
String[] activeProfiles = environment.getActiveProfiles();
// swagger开关
boolean flag = false;
// 判断
for (String activeProfile : activeProfiles) {
// prop则为false
if ("prop".equals(activeProfile)) break;
// 如果是test或dev则开启swagger
if ("test".equals(activeProfile) || "dev".equals(activeProfile)){
flag = true;
break;
}
}
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo)
// swagger开关 根据环境配置文件来决定
.enable(flag)
.select()
// 扫描指定包
.apis(RequestHandlerSelectors.withClassAnnotation(RestController.class))
// 指定扫描的路径
.paths(PathSelectors.any())
.build();
}
spring.profiles.active=prod # 此时不会开启
spring.profiles.active=test # 会开启
或则也可以这样
@Bean
public Docket docket(
@Qualifier("apiInfo") ApiInfo apiInfo,
Environment environment) {
// 1 设置要显示swagger的环境
Profiles of = Profiles.of("dev", "test");
// 2 判断当前是否处于该环境
// 通过 enable() 接收此参数判断是否要显示
boolean flag = environment.acceptsProfiles(of);
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo)
// swagger开关 根据环境配置文件来决定
.enable(flag)
.select()
// 扫描指定包
.apis(RequestHandlerSelectors.withClassAnnotation(RestController.class))
// 指定扫描的路径
.paths(PathSelectors.any())
.build();
}
多个API分组
默认的api分组的名称为default,可以通过指定groupName()来指定
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo)
// swagger开关 根据环境配置文件来决定
.enable(flag)
.groupName("wcy") // 分组名称
.select()
// 扫描指定包
.apis(RequestHandlerSelectors.withClassAnnotation(RestController.class))
// 指定扫描的路径
.paths(PathSelectors.any())
.build();
多个分组配置多个Docket即可,可以在不同的Docket中配置不同的操作操作
@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");
}
实体配置
-
@ApiModel为类添加注释
-
@ApiModelProperty为类属性添加注释
@ApiModel("用户实体")
public class User {
@ApiModelProperty("用户名")
public String username;
@ApiModelProperty("密码")
public String password;
}
在controller中返回User就可以将其映射到Model中
@GetMapping("/user")
public User user(){
return new User();
}
常用注解
Swagger注解 | 说明 |
---|---|
@Api(tags = “xxx模块说明”) | 作用在模块类上 |
@ApiOperation(“xxx接口说明”) | 作用在接口方法上 |
@ApiModel(“xxxPOJO说明”) | 作用在模型类上:如VO、BO |
@ApiModelProperty(value = “xxx属性说明”,hidden = true) | 作用在类方法和属性上,hidden设置为true可以隐藏该属性 |
@ApiParam(“xxx参数说明”) | 作用在参数、方法和字段上,类似@ApiModelProperty |
@ApiOperation("接口")
@GetMapping("/hello1")
public String hello1(@ApiParam("返回这个名字") String name){
return "hello"+ name;
}
皮肤
默认
bootstrop
<!-- 引入swagger-bootstrap-ui包 /doc.html-->
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>swagger-bootstrap-ui</artifactId>
<version>1.9.1</version>
</dependency>
layerui
<!-- 引入swagger-ui-layer包 /docs.html-->
<dependency>
<groupId>com.github.caspar-chen</groupId>
<artifactId>swagger-ui-layer</artifactId>
<version>1.1.3</version>
</dependency>