swagger是解决前后端对接问题的API框架，用它可以自动生成接口文档
- 准备工作
使用swagger之前需要导入两个依赖
• Springfox-swagger2
• swagger-springmvc
对应的依赖写法：
<!-- 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的默认界面
我们可以在配置类中自定义配置页面的各中信息，比如如下代码
- Swagger的实例Bean是Docket，所以可以通过配置Docket配置swagger
//配置docket以配置Swagger具体参数
@Bean
public Docket docket() {
return new Docket(DocumentationType.SWAGGER_2);
}
- 要配置页面基本信息还需要配置一个apiInfo()属性
private ApiInfo apiInfo() {
Contact contact = new Contact("联系人名字", "http://xxx.xxx.com/联系人访问链接", "联系人邮箱");
return new ApiInfo(
"Swagger学习", // 标题
"学习演示如何配置Swagger", // 描述
"v1.0", // 版本
"http://terms.service.url/链接", // 组织链接
contact, // 联系人信息
"Apach 2.0 许可", // 许可
"许可链接", // 许可连接
new ArrayList<>()// 扩展
);
}
- 将Docket与ApiInfo关联起来
在1的代码上做一些修改
@Bean
public Docket docket() {
return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo());
}
再次运行测试，发现页面信息已经更改为我们设置的了
完整代码
@Configuration//配置类的注解
@EnableSwagger2//开启Swagger2的自动配置
public class SwaggerConfig {
@Bean
public Docket docket(Environment environment){
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo());
}
private ApiInfo apiInfo(){
Contact contact = new Contact("联系人名字","联系人的相关网址","联系人的邮箱");//作者信息
return new ApiInfo( "Swagger学习", // 标题
"学习演示如何配置Swagger", // 描述
"v1.0", // 版本
"http://terms.service.url/组织链接", // 组织链接
contact, // 联系人信息
"Apach 2.0 许可", // 许可
"许可链接", // 许可连接
new ArrayList<>());// 扩展)
}
}
- 配置扫描接口
在配置Docket时可以使用select()方法进行设置扫描接口的方式、范围
这里有扫描接口的几种方式，以basePackge为例
@Bean
public Docket docket() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()// 通过.select()方法，去配置扫描接口,RequestHandlerSelectors配置如何扫描接口
.apis(RequestHandlerSelectors.basePackage("com.xin.swaggerdemo.controller"))
//.apis(RequestHandlerSelectors.basePackage("com.xin.swaggerdemo.controller"))
//此时就设置了只扫描controller包下的接口,com.xin.swaggerdemo是我创建包的结构
.build();
}
此时Swagger页面就只有我自己在controller包下创建的hello-controller,没有之前的basic-error-controller
• 其他配置方式的介绍：
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) // 根据包路径扫描接口
另外还可以对接口名称过滤
如果设置成
就只会扫描以/xin/…形式开头的接口
定义了如下接口
@RequestMapping(value = "/hello")
public String hello(){
return "hello";
}
@RequestMapping(value = "/xin/hello")
public String hello2(){
return "hello xin";
}
@RequestMapping(value = "/hello3")
public String hello3(){
return "x_hello";
}
@RequestMapping(value = "/hello4")
public String hello4(){
return "hello4";
}
最终显示的只有/xin/hello
ps:其他可选值：
any() // 任何请求都扫描
none() // 任何请求都不扫描
regex(final String pathRegex) // 通过正则表达式控制
ant(final String antPattern) // 通过ant()控制
- 配置Swagger开关
- 开发过程中我们需要查看Swagger界面，但当项目上线后就不能给用户查看了，不然有安全隐患
@Bean
public Docket docket(Environment environment){
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo());
.enable(false) //enable设置是否可以查看swagger页面
.apis(RequestHandlerSelectors.basePackage("com.xin.swaggerdemo.controller"))
.build();
}
设置成false之后就无法打开swagger页面了
- 动态配置Swagger开关
配置不同的配置文件，开发用开发的配置环境，上线用上线的配置环境
获取当前配置环境，看是否与当前指定要显示的环境一致，根据比较结果设置boolean b的值，再，使用.enable(b)判断是否允许访问Swagger页面
- 设置API分组（便于团队开发）
当前默认一个Docket，可以通过groupName（）设置名称
可以设置多个Docket，以区分不同人设置的接口文档
@Configuration//配置类的注解
@EnableSwagger2//开启Swagger2的自动配置
public class SwaggerConfig {
@Bean
public Docket docket(Environment environment){
// // 设置要显示swagger的环境
// Profiles of = Profiles.of("dev", "test");
// // 判断当前是否处于该环境
// // 通过 enable() 接收此参数判断是否要显示
// boolean b = environment.acceptsProfiles(of);//获得当前配置环境
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo());
// .groupName("BB")
//.enable(b)
// .select()
// .apis(RequestHandlerSelectors.basePackage("com.xin.swaggerdemo.controller"))
//此时通过 .apis(RequestHandlerSelectors.basePackage("com.xin.swaggerdemo.controller"))
// 设置了只扫描controller包下的接口
//.paths(PathSelectors.ant("/xin/**"))
// .build();
}
private ApiInfo apiInfo(){
Contact contact = new Contact("联系人名字","联系人的相关网址","联系人的邮箱");//作者信息
return new ApiInfo( "Swagger学习", // 标题
"学习演示如何配置Swagger", // 描述
"v1.0", // 版本
"http://terms.service.url/组织链接", // 组织链接
contact, // 联系人信息
"Apach 2.0 许可", // 许可
"许可链接", // 许可连接
new ArrayList<>());// 扩展)
}
@Bean
public Docket docket2(Environment environment){
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.groupName("AA")
.select()
.apis(RequestHandlerSelectors.basePackage("com.xin.swaggerdemo.controller"))
.build();
}
@Bean
public Docket docket3(Environment environment){
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.groupName("CC")
.select()
.apis(RequestHandlerSelectors.basePackage("com.xin.swaggerdemo.controller"))
.build();
}
//这里设置了三个docket，组名设为AA、BB、CC
此时再打开Swagger页面就会显示不同人的接口文档
- 实体配置
当接口返回的是一个对象时，也显示在文档中，并且用注解来添加注释信息
编写一个User实体类，写一个getUser()接口
@ApiModel为类添加注释，可以方便查看文档的人理解
@ApiModelProperty为类属性添加注释
package com.xin.swaggerdemo.pojo;
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
@ApiModel("用户实体")
public class User {
@ApiModelProperty("用户名")
public String username;
@ApiModelProperty("密码")
public String password;
}
再写一个getUser(),返回一个User对象
@RequestMapping( "/getUser")
public User getUser(){
return new User();
}
结果就是
PS:此外，Swagger还可以用来测试接口，让我们不需要再依赖其他工具
