一、什么是Swagger
Swagger是一个规范和完整的框架,用于生成、描述、调用和可视化RESTful风格的Web服务。简单来说,Swagger是一个功能强大的接口管理工具,并且提供了多种编程语言的前后端分离解决方案,帮助后端开发人员与前端人员进行沟通测试,还有postmen,Swagger之前是Alibaba的后面。
二、新建一个SpringBoot-web项目
三、整合Swagger
这里我们选择使用swagger2.9.2经典的版本,我们可以看到2.9.2是使用最多的版本,大家可以进入maven仓库进行搜索查看相关的maven依赖。
1、添加相关maven依赖
<!--swagger-ui -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.9.2</version>
</dependency>
<!--springfox-swagger2 -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.2</version>
</dependency>
2、需要使用Swagger需要我们编写JavaConfig配置
@Configuration //配置类
@EnableSwagger2// 开启Swagger2的自动配置
public class SwaggerConfig {
}
然后启动springboot项目,访问http://localhost:8080/swagger-ui.html,就会出现下图内容,记住不同版本的swagger的访问地址不一样,比如swagger3.0的访问地址为http://localhost:8080/swagger-ui/index.html
3.继续在congfig中配置相关信息
Swagger实例Bean是Docket,所以通过配置Docket实例来配置Swaggger,可以通过apiInfo()属性配置文档信息,Docket 实例关联上 apiInfo()
SwaggerConfig.java
@Configuration //配置类
@EnableSwagger2 //开启swagger2自动配置
public class SwaggerConfig {
//访问地址:http://localhost:8080/swagger-ui.html
//配置了swagger2的Docket的bean实例
@Bean
public Docket docket(Environment environment){
//设置要显示的Swagger环境
Profiles profiles = Profiles.of ("dev","test");
//获取项目的环境 通过environment.acceptsProfiles判断是否处在注解设定的环境中
boolean flag = environment.acceptsProfiles(profiles);
return new Docket(DocumentationType.SWAGGER_2) //链式编程
.apiInfo(apiInfo())
.groupName("誓言")
.enable(flag) //是否开启swagger,默认为开启
.select()
//RequestHandlerSelectors配置要扫描接口的方式
//basePackage("com.rql.controller"):指定要扫描的包,any():扫描全部,none()什么都不扫描
//withClassAnnotation(RestController.class)://扫描类上的注解
//withMethodAnnotation(GetMapping.class): 扫描方法上的注解
.apis(RequestHandlerSelectors.basePackage("com.rql.controller"))
//.paths 过滤什么路径
// .paths(PathSelectors.ant("/rql/**"))
.build();
}
//如何配置多个分组?配置多个分组只需要配置多个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");
}
//配置swagger信息
private ApiInfo apiInfo(){
//作者信息
Contact contact = new Contact("誓言唯美", "http://116.205.172.218/", "123456@qq.com");
return new ApiInfo(
"RQL的API接口日志",
"誓言唯美",
"1.0", "http://116.205.172.218/",
contact,
"Apache 2.0",
"http://www.apache.org/licenses/LICENSE-2.0",
new ArrayList()
);
}
}
重新启动访问,出现下面的内容:
4、新建一个实体类User
并添加相关的Swagger注解,表明这是一个实体
@ApiModel("用户实体")
public class User {
@ApiModelProperty("用户名")
public String username;
@ApiModelProperty("密码")
public String password;
}
5、编写HelloController进行测试,添加相关的注解
@RestController
public class HelloController {
@ApiOperation("Hello控制接口")
@GetMapping("/hello")
public String Hello(){
return "Hello,Swagger!";
}
//只要我们的接口中,返回值存在实体类,就会被扫描到swagger中
@GetMapping("/user")
public User user(){
return new User();
}
@ApiOperation("Hello控制接口AA")
@GetMapping("/hello2")
public String Hello2(@ApiParam("用户名") String username){
return "hello"+username;
}
@ApiOperation("Post测试类")
@PostMapping(value = "/postt")
public User postt(@ApiParam("用户") User user){
return user;
}
}
重新启动出现下面的图片展示
当我们进入某一个接口中,就可以进行相关的测试
6、总结
以上只是简单的Swagger使用,具体的还是需要大家去官网学习,以及挖掘源码学习,以下列一些经常用到的,未列举出来的可以前往官网查询: