什么是 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="turodog@foxmail.com">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", "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 <br/> * Package Name:com.nasus.controller <br/> * Date:2019/1/22 22:07 <br/> * <b>Description:</b> TODO: 描述该类的作用 <br/> * * @author <a href="turodog@foxmail.com">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 地址，结果如下图：
项目源代码
github ： https://github.com/turoDog/Demo/tree/master/swagger2-demo
图解接口
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 感兴趣请长按二维码关注一波，我会努力带给你们价值，如果觉得本文对你哪怕有一丁点帮助，请帮忙点好看，让更多人知道。
