SpringBoot 实战 (五) | 集成 Swagger2 构建强大的 RESTful API 文档

微信公众号：一个优秀的废人
如有问题或建议，请后台留言，我会尽力解决你的问题。

前言

快过年了，不知道你们啥时候放年假，忙不忙。反正我是挺闲的，所以有时间写 blog。今天给你们带来 SpringBoot 集成 Swagger2 的教程。

什么是 Swagger2

Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。

为什么使用 Swagger2 ？

相信刚开始不熟悉 web 开发的时候，大家都有手写 Api 文档的时候。而手写 Api 文档主要有以下几个痛点：

1. 文档需要更新的时候，需要再次发送一份给前端，也就是文档更新交流不及时。
2. 接口返回结果不明确。
3. 不能直接在线测试接口，通常需要使用工具，比如 postman。
4. 接口文档太多，不好管理。

这些痛点在前后端分离的大型项目上显得尤为烦躁。而 Swagger2 的出现恰好能个解决这些痛点。因为 Swagger2 有以下功能：

1. 文档自动更新，只要生成 Api 的网址没变，基本不需要跟前端沟通。
2. 接口返回结果非常明确，包括数据类型，状态码，错误信息等。
3. 可以直接在线测试文档，而且还有实例提供给你。
4. 只需要一次配置便可使用，之后只要会有一份接口文档，非常易于管理。

集成演示

首先新建一个 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="[e-mail]">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", "[e-mail]"))
                // 文档版本
                .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="[e-mail]">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

图解接口

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、前端、算法资料分享