从前:
开发人员创建一份 RESTful API 文档来用来记录所有的接口细节。
但是,会有一下问题的出现:
-
API 接口众多,细节复杂,需要考虑不同的HTTP请求类型、HTTP头部信息、HTTP请求内容等,想要高质量的完成这份文档需要耗费大量的精力;
-
难以维护。随着需求的变更和项目的优化、推进,接口的细节在不断地演变,接口描述文档也需要同步修订,可是文档和代码处于两个不同的媒介,除非有严格的管理机制,否则很容易出现文档、接口不一致的情况;
现在:
Swagger2 诞生!!!
Swagger2 可以从根本上解决上述问题,它作为一个规范和完整的框架,可以用于生成、描述、调用和可视化 RESTful 风格的 Web 服务:
-
接口文档在线自动生成,文档随接口变动实时更新,节省维护成本
-
支持在线接口测试,不依赖第三方工具
真的很happy!!!
迫不及待的人儿,下面就来说说怎么完美的使用它吧!
1、pom.xml 添加 Maven 依赖
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.2</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.9.2</version>
</dependency>
注:
springboot项目整合swagger要注意两者的版本,springboot项目的版本低,相应的swagger版本不能太高,反之亦然,避免项目报错,我的springboot版本为2.2.2,swagger版本为2.2.2,项目启动就会报如下错误:这个问题的解决办法就是直接将pom文件中的swagger版本换成2.9.2就可以了!
2、创建 Swagger2.java
package com.kismet.mongotext.config;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
/**
* @author ganqizhi
* @date 2020/9/11 11:27 上午
*/
@Configuration
@EnableSwagger2
public class Swagger2 {
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.basePackage("com.kismet.mongotext.Controller"))
.paths(PathSelectors.any()) // 可以根据url路径设置哪些请求加入文档,忽略哪些请求
.build();
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("kismet的测试服务") //设置文档的标题
.description("kismet的测试服务 API 接口文档") // 设置文档的描述
.version("1.0") // 设置文档的版本信息-> 1.0.0 Version information
.build();
}
}
Swagger2.java 配置类的内容很少,配置完成后也很少变化,了解即可。
如上代码所示,通过 @Configuration
注解,让 Spring 加载该配置类。再通过 @EnableSwagger2
注解来启用Swagger2。成员方法 createRestApi
函数创建 Docket
的Bean之后,apiInfo()
用来创建该 Api 的基本信息,这些基本信息会展现在文档页面中。select()
函数返回一个 ApiSelectorBuilder
实例用来控制哪些接口暴露给 Swagger 来展现,我这里采用指定扫描的包路径来定义,Swagger 会扫描该包下所有 Controller 定义的 API,并产生文档内容,但除了被 @ApiIgnore
指定的请求。
3、API 接口编写
在完成上述配置后,就已经可以产生文档内容,但是这样的文档主要针对请求本身,而描述主要来源于函数等命名产生,对用户并不友好,我们通常需要自己增加一些说明来丰富文档内容。
package com.kismet.mongotext.Controller;
import com.kismet.mongotext.Service.UserService;
import com.kismet.mongotext.config.PageableVo;
import com.kismet.mongotext.config.RequestVo;
import com.kismet.mongotext.entity.MongoUser;
import com.kismet.mongotext.entity.MysqlUser;
import com.kismet.mongotext.entity.User;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.*;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpSession;
import java.util.List;
/**
* @author ganqizhi
* @date 2020/9/4 2:52 下午
*/
@RestController
@RequestMapping("/user")
@Api(description = "生产者进程API接口")
public class UserController {
@Autowired
private UserService userService;
//读取mongodb用户信息同步给mysql
@ApiOperation("读取mongodb用户信息同步给mysql")
@GetMapping("/snycUser")
public List<MysqlUser> findAll(){
return userService.snycUser();
}
//添加mongodb用户信息
@ApiOperation("添加mongodb用户信息")
@PostMapping("/addUser")
public MongoUser addUser(@RequestBody User user){
return userService.addUser(user);
}
//分页查询mysql数据
@ApiOperation("分页查询mysql数据")
@PostMapping("/findPage")
public List<MysqlUser> findByPage(@RequestBody PageableVo<RequestVo,User> users){
return userService.findByPage(users);
}
@ApiOperation("添加mongodb用户信息")
@PostMapping("/findByMongo")
public List<MongoUser> findByMongo(@RequestBody PageableVo<RequestVo,User> users){
return userService.findMongo(users);
}
}
Swagger 通过注解定制接口对外展示的信息,这些信息包括接口名、请求方法、参数、返回信息等。更多注解类型:
- @Api:修饰整个类,描述Controller的作用
- @ApiOperation:描述一个类的一个方法,或者说一个接口
- @ApiParam:单个参数描述
- @ApiModel:用对象来接收参数
- @ApiProperty:用对象接收参数时,描述对象的一个字段
- @ApiResponse:HTTP响应其中1个描述
- @ApiResponses:HTTP响应整体描述
- @ApiIgnore:使用该注解忽略这个API
- @ApiError :发生错误返回的信息
- @ApiImplicitParam:描述一个请求参数,可以配置参数的中文含义,还可以给参数设置默认值
- @ApiImplicitParams:描述由多个 @ApiImplicitParam 注解的参数组成的请求参数列表
4、启动 SpringBoot 应用
SpringBoot 启动成功后,访问http://localhost:8021/swagger-ui.html //端口号需根据自己的端口号进行修改
展开类维度的接口列表,如 user-controller,页面会列出该类中定义的所有接口。点击任意接口,可查看该接口的 url 路径、请求类型、参数描述和返回码说明等信息。
点击右上角的 “Try it out!”
按钮,写入请求信息,点击 Execute
按钮完成一次请求调用!