什么是Swagger
Swagger是一个围绕Open API规范构建的开源工具,可以帮助设计,构建,记录和使用 REST API。
为什么需要Swagger
接口文档对于前后端开发人员都十分重要。尤其近几年流行前后端分离后接口文档又变成重中之重。接口文档固然重要,但是由于项目周期等原因后端人员经常出现无法及时更新,导致前端人员抱怨接口文档和实际情况不一致。很多人员会抱怨别人写的接口文档不规范,不及时更新。当时当自己写的时候确实最烦去写接口文档。这种痛苦只有亲身经历才会牢记于心如果接口文档可以实时动态生成就不会出现上面问题。Swagger 可以完美的解决上面的问题。
Swagger常用注解
@Api
这个注解用于类上,表示标识这个类是swagger的资源
tags–表示说明
value–也是说明,可以使用tags替代
但是tags如果有多个值,会生成多个list
例子:
@Api(description="测试类",tags={"测试类接口"})
@RestController
@RequestMapping("/test")
public class Test(){}
@ApiOperation
用于方法,表示一个http请求的操作
例子:
@ApiOperation(value="测试方法名")
@RequestMapper(value="/test")
public String test(){}
还有很多注解大家可以去慢慢去查看,现在先步入正轨,如何去使用Swagger,练一下手
SpringBoot整合Swagger
首先创建一个SpringBoot项目,这里我就不重新创建新项目了,然后直接使用之前的测试项目来继续
这里我有张表也是之前的,我在这里做一个简单的查询操作,用的框架还是之前的MyBatis-Plus整合的,想先了解MyBatis-Plus可以先我的下面这篇博文熟悉熟悉
博客地址:https://blog.csdn.net/UncleFujii/article/details/111771875
POJO类
@Data
@NoArgsConstructor
@AllArgsConstructor
public class User {
private int id;
private String username;
private String password;
}
Mappper类
@Mapper
public interface UserMapper {
@Select("select * from user")
List<User>getUserList();
}
Controller类
@RestController
@RequestMapping("/user")
public class UserController {
@Resource
private UserMapper userMapper;
@GetMapping("/list")
public String getUserList(){
try {
List<User> list = userMapper.getUserList();
HashMap<String,Object> data = new HashMap<>();
data.put("data",list);
data.put("msg","查询成功");
data.put("code",200);
String s = JSON.toJSONString(data);
return s;
}catch (Exception e){
e.printStackTrace();
return "没有找到任何数据";
}
}
}
访问测试:http://localhost:8080/user/list
{
"msg":"查询成功",
"code":200,
"data"
[{"id":1,"password":"123456","username":"张三"},
{"id":2,"password":"123456","username":"李四"},
{"id":3,"password":"154625","username":"王老五"}]
}
获取到了结果!说明这边是没问题了,然后我们就开始使用我们的Swagger工具生成api文档吧!
步骤
首先引入Swagger依赖
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.7.0</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.7.0</version>
</dependency>
第一个是API获取的包,第二是官方给出的一个ui界面。这个界面可以自定义,默认是官方的,对于安全问题,以及ui路由设置需要着重思考。
然后在创建一个Config包在包里面创建一个SwaggerConfig的类
SwaggerConfig类
@Configuration
@EnableSwagger2
public class SwaggerConfig {
@Bean
public Docket createRestApi(){
return new Docket(DocumentationType.SWAGGER_2)
.protocols(Sets.newHashSet("http")) //协议,http或https
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.basePackage("com.uncletj.mybatisplus.controller"))//controller扫描路径
.paths(PathSelectors.any())
.build();
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("测试Swagger接口文档") //标题
.version("1.0") //版本号
.description("api文档") //内容
.build();
}
}
然后在我刚上面的控制层上加上相应的注解即可
(也是就我上面那两个注解加到Controller上面去)
访问ui界面路径:http://localhost:8080/swagger-ui.html#/
具体文档如下图所示:
这是我刚刚所查询的数据,你只要每次写完操作之后在这个方法上加上@ApiOperation()即可,打开之后可直接查看相应数据
这就是我们刚刚所查到的数据
好了,这期就到这里,中途插个小插曲,本来说是准备ES搜索更新完在更新,不过我后期的ES篇会在每篇写入之前的博文路径,也好让大家找到,咱们下期见