一、swagger简介
官网 ：https://swagger.io
在项目中使用Swagger 需要Springfox
-
Swaggwer
-
ui
Spring集成Swagger
-
新建一个Springboot项目
-
导入相关依赖
<!-- 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>
-
编写一个hello工程
-
配置Swagger------写一个Config
@Configuration
@EnableSwagger2 //开启Swagger2
public class SwaggerConfig {
} -
测试运行
二、配置Swagger
Swagger的bean实例 ------Docket
//配置Swagger的信息---apiInfo
private ApiInfo apiInfo(){
//著者信息
Contact contact = new Contact("马志斌", "https://www.cnblogs.com/hzw6118/", "42334962@qq.com");
return new ApiInfo(
"联安API文档",
"好好学习，天天向上",
"v2.0",
"https://www.cnblogs.com/hzw6118/",
contact,
"Apache 2.0",
"http://www.apache.org/licenses/LICENSE-2.0",
new ArrayList<VendorExtension>());
}
##
三、Swagger配置扫描接口
Docket.select()
public Docket docket() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
//RequestHandlerSelectors,配置要扫描接口的方式
//指定要扫描的包
.apis(RequestHandlerSelectors.basePackage("com.lianan.swagger.controller"))
//过滤什么路径
.paths(PathSelectors.ant("com.lianan.swagger.controller"))
.build(); //此处的参数是ApiInfo类的对象
}
四、配置是否启动Swagger
public class SwaggerConfig {
//配置Swagger的Docket的bean实例
@Bean
public Docket docket() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
//enable是否启动Swagger，如果为false，则不能启动Swagger，不能在浏览器中访问
//.enable(false)
.select()
//RequestHandlerSelectors,配置要扫描接口的方式
//指定要扫描的包
.apis(RequestHandlerSelectors.basePackage("com.lianan.swagger.controller"))
//过滤什么路径
// .paths(PathSelectors.ant("com.lianan.swagger.controller"))
.build(); //此处的参数是ApiInfo类的对象
}
五、配置API文档的分组
.groupName("联安")
六、如何配置多个分组
-
多个Docket即可
//配置Swagger的Docket的bean实例
@Bean
public Docket docket1(Environment environment) {
//设置要显示的项目的环境
Profiles profiles = Profiles.of("dev");
//通过environment.acceptsProfiles(profiles)监听到是否是处在自己设置的环境中
boolean falg = environment.acceptsProfiles(profiles);
return new Docket(DocumentationType.SWAGGER_2)
.groupName("马志斌")
.apiInfo(apiInfo1())
.enable(falg);
}
@Bean
public Docket docket2(Environment environment) {
//设置要显示的项目的环境
Profiles profiles = Profiles.of("dev");
//通过environment.acceptsProfiles(profiles)监听到是否是处在自己设置的环境中
boolean falg = environment.acceptsProfiles(profiles);
return new Docket(DocumentationType.SWAGGER_2)
.groupName("侯金良")
.apiInfo(apiInfo2())
.enable(falg);
}
@Bean
public Docket docket3(Environment environment) {
//设置要显示的项目的环境
Profiles profiles = Profiles.of("dev");
//通过environment.acceptsProfiles(profiles)监听到是否是处在自己设置的环境中
boolean falg = environment.acceptsProfiles(profiles);
return new Docket(DocumentationType.SWAGGER_2)
.groupName("陈斌")
.apiInfo(apiInfo3())
.enable(falg);
}
@Bean
public Docket docket(Environment environment) {
//设置要显示的项目的环境
Profiles profiles = Profiles.of("dev");
//通过environment.acceptsProfiles(profiles)监听到是否是处在自己设置的环境中
boolean falg = environment.acceptsProfiles(profiles);
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.groupName("联安")
//enable是否启动Swagger，如果为false，则不能启动Swagger，不能在浏览器中访问
.enable(falg)
.select()
//RequestHandlerSelectors,配置要扫描接口的方式
//指定要扫描的包
.apis(RequestHandlerSelectors.basePackage("com.lianan.swagger.controller"))
//过滤什么路径
// .paths(PathSelectors.ant("com.lianan.swagger.controller"))
.build(); //此处的参数是ApiInfo类的对象
}
七、实体类配置
@ApiModel("用户类")
public class User {
@ApiModelProperty("姓名")
public String name;
@ApiModelProperty("年龄")
public int wge;
}
========================================
@Data
@AllArgsConstructor
@NoArgsConstructor
@ApiModel("学生类")
public class Student {
@ApiModelProperty("姓名")
private String userName;
@ApiModelProperty("密码")
private String password;
}
八、Controller类
@RestController
public class HelloController {
@GetMapping("/hello")
public String hello(){
return "大家好，我正常启动了！";
}
//只要我们的接口中，返回值中存在实体类，它就会被扫描到Swagger中
@ApiOperation("HelloController控制类接口")
@PostMapping("/user")
public User user(@ApiParam("用户名") String name){
return new User();
}
@GetMapping("/student")
public Student student(){
return new Student();
}
}
九、总结
1. 我们可以通过Swagger给一些难理解的属性或接口增加一些注释信息
-
接口文档实时更新
-
可以在线测试
Swagger是一个优秀的工具，几乎所有大公司都在使用
注意：为节省运行内存，更主要为了安全起见，在发布前，一定要关闭Swagger