Swagger
目录
1. 简介
- 号称世界上最流行的API框架
- RestFul API 文档在线自动生成工具 => API文档与API定义同步更新
- 直接运行, 可以在线测试API接口
- 支持多种语言
- 在项目中使用Swagger需要SpringFox
- Swagger2
- ui
2. SpringBoot集成Swagger
1. 导入依赖
Swagger3.0直接导入Springfox Boot Starter就可以了
<!-- https://mvnrepository.com/artifact/io.springfox/springfox-boot-starter -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-boot-starter</artifactId>
<version>3.0.0</version>
</dependency>
2.X版本需要导入Swagger2.0和UI
<!-- 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>
我们这里还是使用2.X版本
2. 配置Swagger
package com.wang.config;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
@Configuration
//开启Swagger2
@EnableSwagger2
public class SwaggerConfig {
}
注意
- 只要在Swagger配置类上加上@EnableSwagger2注解, 就可以使用Swagger2了
- Swagger的地址为http://localhost:8080/swagger-ui.html
3. Swagger配置
1. 配置Swagger信息
Swagger的Bean实例 ==> Docket
package com.wang.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.service.VendorExtension;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
import java.util.ArrayList;
@Configuration
//开启Swagger2
@EnableSwagger2
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("wang", "https://www.cnblogs.com/wang-sky/", "715180879@qq.com");
return new ApiInfo(
"我的Swagger接口文档",
"这是一个Swagger接口文档",
"V 1.0",
"https://www.cnblogs.com/wang-sky/",
contact,
"Apache 2.0",
"http://www.apache.org/licenses/LICENSE-2.0",
new ArrayList<VendorExtension>());
}
}
这里修改的是Swagger页面的一些信息, 结果如下
注意
- Docket不要忘了注册Bean并返回一个new Docket
- 返回的Docket要传入一个参数指定产生的文档的类型, 我们这里使用 DocumentationType.SWAGGER_2
2. Swagger配置扫描接口
Docket.select()
@Bean
public Docket docket() {
//RequestHandlerSelectors 配置要扫描接口的方式
/*
basePackage 指定要扫描的包
any 扫描全部
none 都不扫描
withClassAnnotation 扫描类上的注解,参数是一个注解的反射对象, 比如 withClassAnnotation(RestController.class)
withMethodAnnotation 扫描方法上的注解
*/
//paths 过滤的路径, 需要传入PathSelectors.xxx 选择过滤的方式
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.basePackage("com.wang.controller"))
.paths(PathSelectors.ant("/wang/**"))
.build();
}
注意
- apis 扫描, 要传入RequestHandlerSelectors.xxx 指定扫描的方式
- basePackage 指定要扫描的包
- any 扫描全部
- none 都不扫描
- withClassAnnotation 扫描类上的注解,参数是一个注解的反射对象, 比如 withClassAnnotation(RestController.class)
- withMethodAnnotation 扫描方法上的注解
- paths 过滤的路径, 需要传入PathSelectors.xxx 选择过滤的方式
- 最后要.build(), 建造者模式, 同时由于这是链式编程, 一定要写!
- select().XXX.XXX...bulid()是一套, 中间可以写的方法是确定的, 不能乱写
3. 配置Swagger是否启动
只在生产环境下使用Swagger, 而在发布的时候不使用的方法
分别建立不同环境的yml
在application中选择启动的环境, 这里选择生产环境
spring:
profiles:
active: dev
配置Swagger
//配置了Swagger的Docket的Bean实例
@Bean
public Docket docket(Environment environment) {
//RequestHandlerSelectors 配置要扫描接口的方式
/*
basePackage 指定要扫描的包
any 扫描全部
none 都不扫描
withClassAnnotation 扫描类上的注解,参数是一个注解的反射对象, 比如 withClassAnnotation(RestController.class)
withMethodAnnotation 扫描方法上的注解
*/
//paths 过滤的路径, 需要传入PathSelectors.xxx 选择过滤的方式
//设置要显示的Swagger环境
Profiles profiles = Profiles.of("dev");
//通过environment.acceptsProfiles, 判断是否处在自己设定的环境当中
boolean flag = environment.acceptsProfiles(profiles);
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.basePackage("com.wang.controller"))
.paths(PathSelectors.ant("/wang/**"))
.build()
.enable(flag);
}
注意
- .enable
- 只能在select().XXX.XXX....bulid() 外面写
- 默认为true, 如果为False, 则Swagger不能在浏览器中访问
- 要用 Profiles profiles = Profiles.of("dev"); 指定激活的环境的名字
- 获得当前的生产环境(application指定的环境), 要给Docket传入一个Environment对象, 其中保存了当前环境的名字
- environment.acceptsProfiles(profiles); 利用此方法获得是否在给定环境的布尔值
4. 配置API文档的分组
.groupName("我的API")
配置多个分组, 只需要配置多个Docket即可
4. 实体类配置
1. 实体类的注解
package com.wang.pojo;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.Data;
@Data
//@Api("注释")
@ApiModel("用户实体类")
public class User {
@ApiModelProperty("用户名")
private String username;
@ApiModelProperty("密码")
private String password;
}
@ApiModel或者@Api在类上
@ApiModelProperty在属性上
属性为私有, 要写getter才能取到属性名
结果显示在Model上
2. 接口类的注解
package com.wang.controller;
import com.wang.pojo.User;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RestController;
@RestController
public class HelloController {
@GetMapping(value = "/hello")
public String hello() {
return "Hello!";
}
//只要我们的接口中, 返回值中存在实体类, 他就会被扫描到Swagger中
@PostMapping("/user")
public User user() {
return new User();
}
//Operation接口
//Get请求中, 如果添加了字段的注释@ApiParam, Swagger无法测试
@ApiOperation("Hello2接口")
@GetMapping("/hello2")
public String hello2(String username) {
return "hello " + username;
}
//Operation接口
@ApiOperation("Hello3接口")
@PostMapping("/hello3")
public User hello3(@ApiParam("用户") User user) {
return user;
}
}
注意
- 只要我们的接口中, 返回值中存在实体类或者字符串, 他就会被扫描到Swagger中
- @ApiOperation 方法的注释
- @ApiParm 参数的注释
- Get请求中, 如果添加了字段的注释@ApiParam, Swagger无法测试
5. 总结
- 我们可以通过Swagger给一些比较难理解的属性或者接口, 增加注释信息
- 接口文档实时更新
- 可以在线测试
- 注意, 在正式发布的时候, 关闭Swagger(出于安全考虑, 而且节省运行内存)