SpringBoot 实战 (五) | 集成 Swagger2 构建强大的 RESTful API 文档
微信公众号:一个优秀的废人
如有问题或建议,请后台留言,我会尽力解决你的问题。
前言
快过年了,不知道你们啥时候放年假,忙不忙。反正我是挺闲的,所以有时间写 blog。今天给你们带来 SpringBoot 集成 Swagger2 的教程。
什么是 Swagger2
Swagger 是一个规范和完整的框架,用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。
为什么使用 Swagger2 ?
相信刚开始不熟悉 web 开发的时候,大家都有手写 Api 文档的时候。而手写 Api 文档主要有以下几个痛点:
- 文档需要更新的时候,需要再次发送一份给前端,也就是文档更新交流不及时。
- 接口返回结果不明确。
- 不能直接在线测试接口,通常需要使用工具,比如 postman。
- 接口文档太多,不好管理。
这些痛点在前后端分离的大型项目上显得尤为烦躁。而 Swagger2 的出现恰好能个解决这些痛点。因为 Swagger2 有以下功能:
- 文档自动更新,只要生成 Api 的网址没变,基本不需要跟前端沟通。
- 接口返回结果非常明确,包括数据类型,状态码,错误信息等。
- 可以直接在线测试文档,而且还有实例提供给你。
- 只需要一次配置便可使用,之后只要会有一份接口文档,非常易于管理。
集成演示
首先新建一个 SpringBoot 项目,还不会的参考我这篇旧文—— 如何使用 IDEA 构建 Spring Boot 工程
构建时,在选择依赖那一步勾选 Web、LomBok、JPA 和 Mysql 依赖。其中 Mysql 可以不勾,因为我这里用于操作实际的数据库,所以我勾选了。
生成 SpringBoot 后的 Pom 文件依赖如下:这里使用的是 2.4.0 的 Swagger2 版本。
<?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> <parent> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-parent</artifactId> <version>2.1.2.RELEASE</version> <relativePath/> <!-- lookup parent from repository --> </parent> <groupId>com.nasus</groupId> <artifactId>swagger2</artifactId> <version>0.0.1-SNAPSHOT</version> <name>swagger2</name> <description>Demo project for Swagger2</description> <properties> <java.version>1.8</java.version> </properties> <dependencies> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-data-jpa</artifactId> </dependency> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-web</artifactId> </dependency> <dependency> <groupId>mysql</groupId> <artifactId>mysql-connector-java</artifactId> <scope>runtime</scope> </dependency> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-test</artifactId> <scope>test</scope> </dependency> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>2.4.0</version> </dependency> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger-ui</artifactId> <version>2.4.0</version> </dependency> </dependencies> <build> <plugins> <plugin> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-maven-plugin</artifactId> </plugin> </plugins> </build> </project>
第二步,在 SpringBoot 启动类(Application)的同级目录新建一个 Swagger 配置类,注意 Swagger2 配置类必须与项目入口类 Application 位于同一级目录,否则生成 Api 文档失败,代码如下:
package com.nasus; 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.service.Contact; import springfox.documentation.spi.DocumentationType; import springfox.documentation.spring.web.plugins.Docket; import springfox.documentation.swagger2.annotations.EnableSwagger2; /** * Project Name:swagger2-demo <br/> * Package Name:com.nasus <br/> * Date:2019/1/22 22:52 <br/> * <b>Description:</b> TODO: 描述该类的作用 <br/> * * @author <a href="[email protected]">nasus</a><br/> * Copyright Notice ========================================================= * This file contains proprietary information of Eastcom Technologies Co. Ltd. * Copying or reproduction without prior written approval is prohibited. * Copyright (c) 2019 ======================================================= */ @Configuration // 启用 Swagger2 @EnableSwagger2 public class Swagger2 { @Bean public Docket createRestApi() { return new Docket(DocumentationType.SWAGGER_2) // 文档信息对象 .apiInfo(apiInfo()) .select() // 被注解的包路径 .apis(RequestHandlerSelectors.basePackage("com.nasus.controller")) .paths(PathSelectors.any()) .build(); } private ApiInfo apiInfo() { return new ApiInfoBuilder() // 标题 .title("springboot 利用 swagger 构建 API 文档") // Api 文档描述 .description("简单优雅的 restful 风格,https://blog.csdn.net/turodog/") .termsOfServiceUrl("https://blog.csdn.net/turodog/") // 文档作者信息 .contact(new Contact("陈志远", "https://github.com/turoDog", "[email protected]")) // 文档版本 .version("1.0") .build(); } }
第三步,配置被注解的 Controller 类,编写各个接口的请求参数,返回结果,接口描述等等,代码如下:
package com.nasus.controller; import com.nasus.entity.Student; import com.nasus.service.StudentService; import io.swagger.annotations.Api; import io.swagger.annotations.ApiImplicitParam; import io.swagger.annotations.ApiImplicitParams; import io.swagger.annotations.ApiOperation; import java.util.List; import org.springframework.beans.factory.annotation.Autowired; import org.springframework.web.bind.annotation.DeleteMapping; import org.springframework.web.bind.annotation.GetMapping; import org.springframework.web.bind.annotation.PathVariable; import org.springframework.web.bind.annotation.PostMapping; import org.springframework.web.bind.annotation.PutMapping; import org.springframework.web.bind.annotation.RequestBody; import org.springframework.web.bind.annotation.RequestMapping; import org.springframework.web.bind.annotation.RequestMethod; import org.springframework.web.bind.annotation.RestController; import springfox.documentation.annotations.ApiIgnore; /** * Project Name:swagger2-demo <br/> * Package Name:com.nasus.controller <br/> * Date:2019/1/22 22:07 <br/> * <b>Description:</b> TODO: 描述该类的作用 <br/> * * @author <a href="[email protected]">nasus</a><br/> * Copyright Notice ========================================================= * This file contains proprietary information of Eastcom Technologies Co. Ltd. * Copying or reproduction without prior written approval is prohibited. * Copyright (c) 2019 ======================================================= */ @RestController @RequestMapping("/student") // @Api:修饰整个类,描述Controller的作用 @Api("StudentController Api 接口文档") public class StudentController { @Autowired private StudentService studentService; // @ApiOperation:描述一个类的一个方法,或者说一个接口 @ApiOperation(value="获取所有学生列表", notes="获取所有学生列表") @RequestMapping(value={""}, method= RequestMethod.GET) public List<Student> getStudent() { List<Student> list = studentService.findAll(); return list; } @ApiOperation(value="添加学生信息", notes="添加学生信息") // @ApiImplicitParam:一个请求参数 @ApiImplicitParam(name = "student", value = "学生信息详细实体", required = true, dataType = "Student") @PostMapping("/save") public Student save(@RequestBody Student student){ return studentService.save(student); } @ApiOperation(value="获学生信息", notes="根据url的id来获取学生详细信息") @ApiImplicitParam(name = "id", value = "ID", required = true, dataType = "Integer",paramType = "path") @GetMapping("/{id}") public Student findById(@PathVariable("id") Integer id){ return studentService.findById(id); } @ApiOperation(value="删除学生", notes="根据url的id来指定删除的学生") @ApiImplicitParam(name = "id", value = "学生ID", required = true, dataType = "Integer",paramType = "path") @DeleteMapping("/{id}") public String deleteById(@PathVariable("id") Integer id){ studentService.delete(id); return "success"; } @ApiOperation(value="更新学生信息", notes="根据url的id来指定更新学生信息") // @ApiImplicitParams:多个请求参数 @ApiImplicitParams({ @ApiImplicitParam(name = "id", value = "学生ID", required = true, dataType = "Integer",paramType = "path"), @ApiImplicitParam(name = "student", value = "学生实体student", required = true, dataType = "Student") }) @PutMapping(value="/{id}") public String updateStudent(@PathVariable Integer id, @RequestBody Student student) { Student oldStudent = this.findById(id); oldStudent.setId(student.getId()); oldStudent.setName(student.getName()); oldStudent.setAge(student.getAge()); studentService.save(oldStudent); return "success"; } // 使用该注解忽略这个API @ApiIgnore @RequestMapping(value = "/hi", method = RequestMethod.GET) public String jsonTest() { return " hi you!"; } }
第四步,启动项目,访问 http://localhost:8080/swagger-ui.html 地址,结果如下图:
项目源代码
图解接口
Swagger2 常用注解简介
@ApiOperation:用在方法上,说明方法的作用 1.value: 表示接口名称 2.notes: 表示接口详细描述 @ApiImplicitParams:用在方法上包含一组参数说明 @ApiImplicitParam:用在@ApiImplicitParams注解中,指定一个请求参数的各个方面 1.paramType:参数位置 2.header 对应注解:@RequestHeader 3.query 对应注解:@RequestParam 4.path 对应注解: @PathVariable 5.body 对应注解: @RequestBody 6.name:参数名 7.dataType:参数类型 8.required:参数是否必须传 9.value:参数的描述 10.defaultValue:参数的默认值 @ApiResponses:用于表示一组响应 @ApiResponse:用在@ApiResponses中,一般用于表达一个错误的响应信息 1.code:状态码 2.message:返回自定义信息 3.response:抛出异常的类 @ApiIgnore: 表示该接口函数不对swagger2开放展示 @Api:修饰整个类,描述Controller的作用 @ApiParam:单个参数描述 @ApiModel:用对象来接收参数 @ApiProperty:用对象接收参数时,描述对象的一个字段 @ApiIgnore:使用该注解忽略这个API @ApiError :发生错误返回的信息
注意事项
@ApiImplicitParam 注解下的 paramType 属性,会影响接口的测试,如果设置的属性跟spring 的注解对应不上,会获取不到参数,例如 paramType=path ,函数内却使用@RequestParam 注解,这样,可能会获取不到传递进来的参数,需要按照上面进行对应,将 @RequestParam 注解改为 @PathVariable 才能获取到对应的参数。
后语
以上就是我对 Swagger2 的理解与使用,以上只是教大家入门 Swagger2 ,想要深入使用还是希望自行查阅官方文档。最后,对 Python 、Java 感兴趣请长按二维码关注一波,我会努力带给你们价值,如果觉得本文对你哪怕有一丁点帮助,请帮忙点好看,让更多人知道。
另外,关注之后在发送 1024 可领取免费学习资料。资料内容详情请看这篇旧文:Python、C++、Java、Linux、Go、前端、算法资料分享