SpringBoot Swagger
华仔仔coding 人气:01. Swagger 介绍
在一个项目开发过程中,当前端开发人员根据后端开发人员给出的 API 接口文档进行接口联调对接时,可能会出现这样的矛盾:前端开发人员抱怨后端开发人员给出的 API 接口文档和实际的情况有所出入,而后端开发人员由于繁重的开发任务已经身心俱疲,想到自己还要负责维护接口文档的任务更是不堪重负。
这时就需要一个解决方案,希望它能够在后端开发人员进行接口开发时,能够帮助后端工程师自动生成相应的接口文档,当接口有变化时,也能够对文档进行及时更新,这样前端工程师在进行接口联调时,不会再出现发现文档和实际情况不一致的情况。
幸运的是,伟大的开源社区就给出了这样的一套解决方案,称为 Swagger,正如它的中译一样,让后端工程师能够大摇大摆地走,以后再面对前端工程师时神奇十足哈哈!
Swagger 是一个规范和完整的框架,它用于生成、描述、调用和可视化 RESTful 风格的 Web 服务,避免手动维护 API 文档的带来的麻烦。
后端工程师只需要按照它的规范去定义接口及接口相关的信息,再通过 Swagger 衍生出来的一系列项目和工具,就可以做到生成各种格式的接口文档,生成多种语言的客户端和服务端的代码,以及在线接口调试页面等等。
这样,如果按照新的开发模式,在开发新版本或者迭代版本的时候,只需要更新 Swagger 描述文件,就可以自动生成接口文档和客户端服务端代码,做到调用端代码、服务端代码以及接口文档的一致性。
2. 使用Swagger接口文档框架
为了简化 Swagger 的使用,Spring 框架对 Swagger 进行了整合,建立了 Spring-Swagger 项目,之后又更新作 Springfox. 通过在项目中引入 Springfox,可以扫描相关的代码,生成描述文件以及与代码一致的接口文档和客户端代码。
引入 Springfox 的 maven 坐标如下
<dependency> <!--swagger 文档的 UI 组件--> <groupId>io.springfox</groupId> <artifactId>springfox-swagger-ui</artifactId> <version>2.9.2</version> </dependency> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>2.9.2</version> </dependency>
Swagger 常用的注解及对应的描述如下表所示:
注解 | 描述 |
---|---|
@Api | 用在请求的类上,例如 @Controller,表示对类的说明 |
@ApiModel | 用在类上,通常是实体类,表示一个返回响应数据的信息 |
@ApiModelProperty | 用在属性上,描述响应类的属性 |
@ApiOperation | 用在请求的方法上,说明方法的用途、作用 |
@ApiImplicitParams | 用在请求的方法上,表示一组参数说明 |
@ApiImplicitParam | 用在 @ApiImplicitParams 注解中,指定一个请求参数的各个方面 |
下面就开始着手在 SpringBoot 项目中使用 Swagger 文档接口。
第一步,创建一个名为 swagger_demo 的 maven 工程,工程的 pom.xml 文件内容如下
<?xml version="1.0" encoding="UTF-8"?> <project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd"> <modelVersion>4.0.0</modelVersion> <groupId>com.hzz</groupId> <artifactId>swagger_demo</artifactId> <version>1.0-SNAPSHOT</version> <properties> <java.version>1.8</java.version> </properties> <parent> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-parent</artifactId> <version>2.2.2.RELEASE</version> <relativePath/> </parent> <dependencies> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-web</artifactId> </dependency> <!--swagger 文档的 UI 组件--> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger-ui</artifactId> <version>2.9.2</version> </dependency> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>2.9.2</version> </dependency> <dependency> <groupId>org.projectlombok</groupId> <artifactId>lombok</artifactId> </dependency> </dependencies> </project>
第二步,在 resources 目录下创建 application.yml 文件
server:
port: 9000 #指定服务端口号
第三步,创建实体类 User 和 Menu
User 类
package com.hzz.entity; import io.swagger.annotations.ApiModel; import io.swagger.annotations.ApiModelProperty; import lombok.Data; @Data @ApiModel(description = "用户实体") public class User { @ApiModelProperty(value = "主键") private int id; @ApiModelProperty(value = "姓名") private String name; @ApiModelProperty(value = "年龄") private int age; @ApiModelProperty(value = "地址") private String address; }
Menu 类
package com.hzz.entity; import io.swagger.annotations.ApiModel; import io.swagger.annotations.ApiModelProperty; import lombok.Data; @Data @ApiModel(description = "菜单实体") public class Menu { @ApiModelProperty(value = "主键") private int id; @ApiModelProperty(value = "菜单名称") private String name; }
第四步,创建 UserController 和 MenuController
UserController 类
package com.hzz.controller.user; import com.hzz.entity.User; import io.swagger.annotations.Api; import io.swagger.annotations.ApiImplicitParam; import io.swagger.annotations.ApiImplicitParams; import io.swagger.annotations.ApiOperation; import org.springframework.web.bind.annotation.*; import java.util.ArrayList; import java.util.List; @RestController @RequestMapping("/user") @Api(tags = "用户控制器") public class UserController { @GetMapping("/getUsers") @ApiOperation(value = "查询所有用户", notes = "查询所有用户信息") public List<User> getAllUsers() { User user = new User(); user.setId(100); user.setName("hzz"); user.setAge(20); user.setAddress("hz"); List<User> list = new ArrayList<>(); list.add(user); return list; } @PostMapping("/save") @ApiOperation(value = "新增用户", notes = "新增用户信息") public String save(@RequestBody User user) { return "OK"; } @PutMapping("/update") @ApiOperation(value = "修改用户", notes = "修改用户信息") public String update(@RequestBody User user) { return "OK"; } @DeleteMapping("/delete") @ApiOperation(value = "删除用户", notes = "删除用户信息") public String delete(int id) { return "OK"; } @ApiImplicitParams({ @ApiImplicitParam(name = "pageNum", value = "页码", required = true, type = "Integer"), @ApiImplicitParam(name = "pageSize", value = "每页条数", required = true, type = "Integer"), }) @ApiOperation(value = "分页查询用户信息") @GetMapping(value = "page/{pageNum}/{pageSize}") public String findByPage(@PathVariable Integer pageNum, @PathVariable Integer pageSize) { return "OK"; } }
MenuController 类
package com.hzz.controller.menu; import com.hzz.entity.Menu; import io.swagger.annotations.Api; import io.swagger.annotations.ApiImplicitParam; import io.swagger.annotations.ApiImplicitParams; import io.swagger.annotations.ApiOperation; import org.springframework.web.bind.annotation.*; import java.util.ArrayList; import java.util.List; @RestController @RequestMapping("/menu") @Api(tags = "菜单控制器") public class MenuController { @GetMapping("/getMenus") @ApiOperation(value = "查询所有菜单", notes = "查询所有菜单信息") public List<Menu> getMenus() { Menu menu = new Menu(); menu.setId(100); menu.setName("hzz"); List<Menu> list = new ArrayList<>(); list.add(menu); return list; } @PostMapping("/save") @ApiOperation(value = "新增菜单", notes = "新增菜单信息") public String save(@RequestBody Menu menu) { return "OK"; } @PutMapping("/update") @ApiOperation(value = "修改菜单", notes = "修改菜单信息") public String update(@RequestBody Menu menu) { return "OK"; } @DeleteMapping("/delete") @ApiOperation(value = "删除菜单", notes = "删除菜单信息") public String delete(int id){ return "OK"; } @ApiImplicitParams({ @ApiImplicitParam(name = "pageNum", value = "页码", required = true, type = "Integer"), @ApiImplicitParam(name = "pageSize", value = "每页条数", required = true, type = "Integer"), }) @ApiOperation(value = "分页查询菜单信息") @GetMapping(value = "page/{pageNum}/{pageSize}") public String findByPage(@PathVariable Integer pageNum, @PathVariable Integer pageSize) { return "OK"; } }
第五步,创建 SwaggerAutoConfiguration 配置类
package com.hzz.config; import org.springframework.context.annotation.Bean; import org.springframework.context.annotation.Configuration; import springfox.documentation.builders.ApiInfoBuilder; import springfox.documentation.builders.RequestHandlerSelectors; import springfox.documentation.service.ApiInfo; import springfox.documentation.service.Contact; import springfox.documentation.spi.DocumentationType; import springfox.documentation.spring.web.plugins.Docket; import springfox.documentation.swagger2.annotations.EnableSwagger2; /** * 自动配置类 */ @Configuration @EnableSwagger2 //启动swagger public class SwaggerAutoConfiguration { @Bean public Docket createRestApi1() { //docket 用于封装接口文档相关信息 Docket docket = new Docket(DocumentationType.SWAGGER_2) .apiInfo(apiInfo()) .apiInfo(apiInfo()).groupName("用户接口组") .select() //为当前包路径 .apis(RequestHandlerSelectors.basePackage("com.hzz.controller.user")) .build(); return docket; } @Bean public Docket createRestApi2() { //docket 用于封装接口文档相关信息 Docket docket = new Docket(DocumentationType.SWAGGER_2) .apiInfo(apiInfo()).groupName("菜单接口组") .select() //为当前包路径 .apis(RequestHandlerSelectors.basePackage("com.hzz.controller.menu")) .build(); return docket; } //构建 API 文档的详细信息 private ApiInfo apiInfo() { return new ApiInfoBuilder() .title("API接口文档") //页面标题 //联系人 .contact(new Contact("华仔仔coding", null,null)) //url和email没有则填充null即可 .version("1.0") //版本号 .description("API 描述") //描述 .build(); } }
第六步,创建启动类
package com.hzz; import org.springframework.boot.SpringApplication; import org.springframework.boot.autoconfigure.SpringBootApplication; @SpringBootApplication public class SwaggerDemoApplication { public static void main(String[] args) { SpringApplication.run(SwaggerDemoApplication.class, args); } }
第七步,启动项目,访问地址 http://localhost:9000/swagger-ui.html,swagger 接口文档可视化界面如下
此外,还可以在文档中进行测试,可以点击某个请求,例如测试上图中的 DELETE 请求,点击 Try it out 进行测试接口
然后,输入请求的参数,点击 Execute 执行,便可以在 Server response 下方看到响应结果
当然,还可以测试其他的接口,观察响应数据,为了使得篇幅不那么冗长,这里就不再演示了吗,以上便是在 SpringBoot 项目中使用 Swagger 接口文档演示的整个过程。
加载全部内容