【快速上手系列】使用Springboot集成Swagger2的简单使用测试
简介
Swagger2是为了解决企业中接口(api)中定义统一标准规范的文档生成工具。 尤其是前后端分离时对一些业务接口也不太方便,接下来进行一下简单的使用测试。
使用步骤
创建一个springboot项目,如果你不会创建可以看这里:【快速搭建系列】idea傻瓜式快速搭建springboot框架
1、导入jar包
添加maven依赖
pom.xml
<!--swagger2依赖-->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.2</version>
</dependency>
<!--视图逻辑swagger-ui-->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.9.2</version>
</dependency>
2、添加注解
在springboot启动类添加@EnableSwagger2
注解
/**
* @Author Tuerlechat,
* @Date 2022/12/5
*/
@SpringBootApplication
@EnableSwagger2 //开启swagger2
public class Swagger2 {
public static void main(String[] args) {
SpringApplication.run(Swagger2.class,args);
}
}
tips:@EnableSwagger2会扫描当前类所在包,及子包中所有的类型中的注解(毕竟都放到启动类上了😂)
3、创建需要访问的类
我这里创建了一个测试的controller
IndexController.java
/**
* @Author Tuerlechat,
* @Date 2022/12/5
*/
@Api(tags = "swagger2测试") //自定义一个类的标签名,在页面接口处显示
@RestController
public class IndexController {
@ApiOperation(value = "用于测试post请求") //测试接口的解释
@PostMapping("/imPost") //post请求
public String imPost(String str) {
return "我是post请求,str==" + str;
}
@ApiOperation(value = "用于测试get请求")
@GetMapping("/imGet") //get请求
public String imGet(String str) {
return "我是get请求,str==" + str;
}
@RequestMapping("/imRequest") //这种请求方式是不限制请求方式的,任意请求方式都可以访问
public String imRequest(String str) {
return "我是RequestMapping,str==" + str;
}
}
然后我们启动服务器
访问 Swagger UI
然后可以看到成功显示页面,我们可以在上面看到自己写的相应接口信息
解释
图上三个方框分别是我写的三个controller方法
接口上也有相应的一些访问路径
可以看到标题对应了类上的
@Api(tags = "xxxx")
注解,右边是我写接口的类名请求接口的方法对应了方法中的
@ApiOperation(value = "xxxx")
注解,在接口的右面进行接口的一些相应解释Get请求和Post请求因为设定了所以都是一个
RequestMapping因为没有对请求进行限制,所以显示出了相应请求的所有接口
点击相应的接口可以看到上面显示接口的参数和响应信息,然后我们可以点击Try it out来测试接口参数
然后在参数中输入值,点击Execute来执行,查看接口返回响应结果即可
tips:上面显示了一些命令和请求头等信息,绿色框上可以看到接口的请求url
设置配置文件来进行一些自定义操作
创建一个swagger2配置类来进行一些自定义操作
SwaggerConfig.java
/**
* @Author Tuerlechat,
* @Date 2022/12/5
*/
@Configuration //设置配置类
@EnableSwagger2 //开启swagger2
public class SwaggerConfig {
@Bean
public Docket webApiConfig(){
return new Docket(DocumentationType.SWAGGER_2)
.groupName("主页api接口") //起一个分组名
.apiInfo(webApiInfo()) //添加下面对应的方法
.select()
//过滤掉admin路径下的所有页面
.paths(Predicates.not(PathSelectors.regex("/admin/.*")))
//过滤掉所有error或error.*页面(默认有一个error页面)
.paths(Predicates.not(PathSelectors.regex("/error.*")))
.build();
}
@Bean
public Docket adminApiConfig(){
return new Docket(DocumentationType.SWAGGER_2)
.groupName("管理员api接口") //起一个分组名
.apiInfo(adminApiInfo()) //添加下面对应的方法
.select()
//只显示admin路径下的页面
.paths(Predicates.and(PathSelectors.regex("/admin/.*")))
.build();
}
/**
* 对应上面的实现方法
* @return
*/
private ApiInfo webApiInfo(){
return new ApiInfoBuilder()
.title("swagger2—测试API文档") //标题
.description("本文档描述了对swagger2进行使用测试") //描述
.version("1.3") //版本
//网站访问跳转链接和发送邮箱
.contact(new Contact("我的主页",
"https://blog.csdn.net/weixin_55452293?spm=1010.2135.3001.5343",
"111111@qq.com"))
.build();
}
/**
* 对应上面的实现方法
* @return
*/
private ApiInfo adminApiInfo(){
return new ApiInfoBuilder()
.title("swagger2-测试使用API文档2")
.description("本文档描述了对swagger2进行使用测试的一些信息")
.version("1.0")
.contact(new Contact("管理员admin", "https://blog.csdn.net/weixin_55452293?spm=1010.2135.3001.5343", "111111@qq.com"))
.build();
}
}
然后再创建一个controller用于测试
AdminController.java
/**
* @Author Tuerlechat,
* @Date 2022/12/5
*/
@Api(tags = "admin测试")
@RestController
@RequestMapping("/admin")
public class AdminController {
@ApiOperation(value = "这是admin接口测试")
@PostMapping("/imAdmin") //post请求
public String imAdmin(@ApiParam(name = "str", value = "张三", required = true) String str) {
return "我是admin接口。";
}
}
然后运行服务器,访问或刷新 Swagger UI
可以看到相应的显示信息都改变了
然后可以点击右上角的分组类别来选中管理员api接口
可以看到相应的信息也更改了
这样就可以了🤓