微信公众号：一个优秀的废人 如有问题或建议，请后台留言，我会尽力解决你的问题。
前言
快过年了，不知道你们啥时候放年假，忙不忙。反正我是挺闲的，所以有时间写 blog。今天给你们带来 SpringBoot 集成 Swagger2 的教程。
什么是 Swagger2
Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。
为什么使用 Swagger2 ？
相信刚开始不熟悉 web 开发的时候，大家都有手写 Api 文档的时候。而手写 Api 文档主要有以下几个痛点：
- 文档需要更新的时候，需要再次发送一份给前端，也就是文档更新交流不及时。
- 接口返回结果不明确。
- 不能直接在线测试接口，通常需要使用工具，比如 postman。
- 接口文档太多，不好管理。
这些痛点在前后端分离的大型项目上显得尤为烦躁。而 Swagger2 的出现恰好能个解决这些痛点。因为 Swagger2 有以下功能：
- 文档自动更新，只要生成 Api 的网址没变，基本不需要跟前端沟通。
- 接口返回结果非常明确，包括数据类型，状态码，错误信息等。
- 可以直接在线测试文档，而且还有实例提供给你。
- 只需要一次配置便可使用，之后只要会有一份接口文档，非常易于管理。
集成演示
首先新建一个 SpringBoot 项目，还不会的参考我这篇旧文——
构建时，在选择依赖那一步勾选 Web、LomBok、JPA 和 Mysql 依赖。其中 Mysql 可以不勾，因为我这里用于操作实际的数据库，所以我勾选了。
生成 SpringBoot 后的 Pom 文件依赖如下：这里使用的是 2.4.0 的 Swagger2 版本。
4.0.0 org.springframework.boot spring-boot-starter-parent 2.1.2.RELEASE com.nasus swagger2 0.0.1-SNAPSHOT swagger2 Demo project for Swagger2 1.8 org.springframework.boot spring-boot-starter-data-jpa org.springframework.boot spring-boot-starter-web mysql mysql-connector-java runtime org.springframework.boot spring-boot-starter-test test io.springfox springfox-swagger2 2.4.0 io.springfox springfox-swagger-ui 2.4.0 org.springframework.boot spring-boot-maven-plugin
第二步，在 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 * Package Name:com.nasus * Date:2019/1/22 22:52 * Description: TODO: 描述该类的作用 * * @author nasus * 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@EnableSwagger2public 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", "turodog@foxmail.com")) // 文档版本 .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 * Package Name:com.nasus.controller * Date:2019/1/22 22:07 * Description: TODO: 描述该类的作用 * * @author nasus * 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 ListgetStudent() { List 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!"; }}
第四步，启动项目，访问 :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 可领取免费学习资料。资料内容详情请看这篇旧文：
