SpringBoot中整合Swagger2生成接口文档

为什么要用Swagger2？

在开发过程中为了减少平时与其他团队的频繁沟通成本，我们通常会创建一份RESTful API文档来记录所有接口的细节，但是这样做的话会有一些问题：

1. 一个大型的项目往往会有超级多的接口，由于接口数量众多，而且细节比较复杂，高质量的把这份文档编写完成，本身就是一个超级困难的事情，下层编写文档的程序员们怨声不绝于耳。
2. 随着时间的推移，会不断修改接口的实现，这个时候也就必须要修改接口文档，而文档与代码又处于两个不同的媒介，除非有严格的管理机制，不然很容易导致不一致现象。

---

为了解决这些问题，给大家介绍一下RESTful API文档的重磅好伙伴Swagger2，它可以轻轻松松整合进Spring Boot中，并与Spring MVC程序配合组织出强大的RESTful API文档。它既可以减少我们创建文档的工作量，同时说明内容又整合入实现代码中，让维护文档和修改代码整合为一体，可以让我们在修改代码逻辑的同时方便的修改文档说明。另外Swagger2也提供了强大的页面测试功能来调试每个RESTful API。

---

下面开始进行整合，首先在pom.xml中加入Swagger2的依赖:

<dependency>
	<groupId>io.springfox</groupId>
	<artifactId>springfox-swagger2</artifactId>
	<version>2.6.1</version>
</dependency>

<dependency>
	<groupId>io.springfox</groupId>
	<artifactId>springfox-swagger-ui</artifactId>
	<version>2.6.1</version>
</dependency>

接下来编写Swagger配置类，加上@Configuration注解，这个类的东西其实只需要了解具体能配置哪些东西就行了，毕竟这个类配置一次以后就不再改了。需要注意的是里面是配置了Controller包的路径，不然扫描不到接口。

package com.test.swagger.demo;

import org.springframework.context.annotation.Bean;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;

/**
 * @Auther: 马旭辉
 * @Date: 2019/4/27 14:49
 * @Description: Swagger2配置类
 */
@Configuration
public class SwaggerConfig {
    public class Swagger2 {

        @Bean
        public Docket createRestApi() {
            return new Docket(DocumentationType.SWAGGER_2)
                    .apiInfo(apiInfo())
                    .select()
                    .apis(RequestHandlerSelectors.basePackage("com.test.swagger.demo.controller"))
                    .paths(PathSelectors.any())
                    .build();
        }
		//用来创建该Api的基本信息
        private ApiInfo apiInfo() {
            return new ApiInfoBuilder()
                    .title("Swagger2构建api文档")
                    .description("说明文字XXX")
                    .termsOfServiceUrl("https://www.csdn.net/")
                    .version("1.0")
                    .build();
        }
    }
}

在Spring Boot的启动类上加入注解@EnableSwagger2，表示开启Swagger。

@SpringBootApplication
@EnableSwagger2
public class DemoApplication {

    public static void main(String[] args) {
        SpringApplication.run(DemoApplication.class, args);
    }

}

下一步是编写Restful接口，在这之前我们先建立一个实体类：

public class User implements Serializable{
    private int id;
    private String name;
    private int age;
    //此处省略 Getter和 Setter方法
}

package com.test.swagger.demo.controller;

import com.test.swagger.demo.bean.User;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.RestController;
import java.util.HashMap;

/**
 * @Auther: 马旭辉
 * @Date: 2019/4/27 15:14
 * @Description:
 */
@RestController
public class UserController {
    //创建一个Map用来存储User对象，模拟数据库操作
    static HashMap<Integer, User> userHashMap = new HashMap<>();

    //往Map里塞入一些数据
    static {
        userHashMap.put(1, new User(1, "蔡徐坤", 26));
        userHashMap.put(2, new User(2, "吴亦凡", 24));
        userHashMap.put(3, new User(3, "孙悟空", 344));
        userHashMap.put(4, new User(4, "二师兄", 119));
    }

    @ApiOperation(value = "获取用户信息", notes = "根据id获取用户详细信息")
    @ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "Integer", paramType = "path")
    @GetMapping("user/{id}")
    public User getUserById(@PathVariable Integer id) {
        User user = userHashMap.get(id);//查询数据
        //返回数据
        return user;
    }
}

启动项目，访问 http://localhost:8080/swagger-ui.html

看到这个页面说明成功进入了Swagger2，这里会显示我们添加的描述文字，然后我们输入一个1进行测试一下：

很明显这个接口测试成功了，已经显示出来了查询结果：

项目结构如下：

最后说一下Swagger2的注解，Swagger通过注解表明该接口会生成文档，包括接口名、请求方法、参数、返回信息的等等：

• @Api：修饰整个类，描述Controller的作用
• @ApiOperation：描述一个类的一个方法，或者说一个接口
• @ApiParam：单个参数描述
• @ApiModel：用对象来接收参数
• @ApiProperty：用对象接收参数时，描述对象的一个字段
• @ApiResponse：HTTP响应其中1个描述
• @ApiResponses：HTTP响应整体描述
• @ApiIgnore：使用该注解忽略这个API
• @ApiError ：发生错误返回的信息
• @ApiImplicitParam：一个请求参数
• @ApiImplicitParams：多个请求参数

欢迎关注微信公众号"程序员小辉"