Spring Boot API 接口文档 Swagger 入门

1. 概述
2. 快速入门 Swagger
3. 更好看的 Swagger UI 界面
4. 更强大的 YApi

概述
目前，大多数系统都采用前后端分离。在享受前后端分离的好处的同时，接口联调往往成为团队效率的瓶颈，甚至产生前后端的矛盾。简单归结来说，有几方面的原因：
问题一，接口设计滞后。 后端团队往往不喜欢 API 接口设计先行，提前和前端沟通好接口。而在开发阶段的中后期，在后端提供 API 接口后，而这些接口和前端的预期有一些偏差，很容易就产生抱怨，特别是项目周期比较紧张的情况下。
问题二，接口不规范。 当团队里没有同意明确的接口规范时，又或者代码 Review 做的不是很好的情况下，千奇百怪、各式各样的 API 接口可能就产生了。前端在对接这样的 API 接口，苦不堪言，在一口 mmp 一嘴 fuck xxx 之中，调完接口。
问题三，接口文档更新不及时，或者遗忘更新。 因为后端 API 代码和 API 接口在两个地方，我们无法保证提交 API 代码的同时，及时更新文档。有的时候，我们甚至会遗忘更新 API 接口。随着时间的流逝，API 文档和 API 接口不一致的地方越来越多，前端会对 API 接口的信任度越来越低，然后不知道不觉之中，回到原始时代，直接问后端开发 API 是什么样的。
对于问题一和问题二，更多是开发流程上的问题，所以不在本文的范围内。当然话痨的艿艿，还是要给点粗浅的建议，完全拦不住我啊。
接口设计先行。设计完成后，后端和前端进行简单沟通，看看是否能够满足诉求。
统一的接口规范。一定要制定统一的接口规范文档，即使比较简陋，也能保证团队的 API 接口相对统一一致。😈 即使错，咱也错的一模一样，而不是千奇百怪。当然，接口规范是无法覆盖到所有的场景的，借助于“接口设计先行”，我们可以提前去 Review 每个接口的设计。
对于问题三，就进入了本文的主角 Swagger 。通过在 API 接口上，添加相应的 Swagger 提供的注解，自动生成 API 文档。酱紫，API 接口和文档就在一起了，从此过上了幸福快乐的生活。
FROM 《RESTful 风格的 Web 服务框架 Swagger》
Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。
总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法、参数和模型紧密集成到服务器端的代码，允许 API 来始终保持同步。Swagger 让部署管理和使用功能强大的 API 从未如此简单。

2. 快速入门 Swagger
示例代码对应仓库：lab-24-apidoc-swagger 。
在本小节，我们来快速入门 Swagger ，可以更加直观的感受到其提供的便利性。
2.1 引入依赖
在 pom.xml 文件中，引入相关依赖。

<?xml version="1.0" encoding="UTF-8"?>

org.springframework.boot
spring-boot-starter-parent
2.1.3.RELEASE


4.0.0

<artifactId>lab-24-apidoc-swagger</artifactId>

<dependencies>
    <!-- 实现对 Spring MVC 的自动化配置 -->
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
    </dependency>

    <!-- 引入 Swagger 依赖 -->
    <dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger2</artifactId>
        <version>2.9.2</version>
    </dependency>

    <!-- 引入 Swagger UI 依赖，以实现 API 接口的 UI 界面 -->
    <dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger-ui</artifactId>
        <version>2.9.2</version>
    </dependency>

</dependencies>

具体每个依赖的作用，胖友自己认真看下艿艿添加的所有注释噢。 2.2 SwaggerConfiguration 因为 Spring Boot 暂未提供 Swagger 内置的支持，所以我们需要自己定义配置类。 在 cn.iocoder.springboot.lab24.apidoc.config 包路径下，创建 SwaggerConfiguration 配置类，用于配置 Swagger 。代码如下： // SwaggerConfiguration.java

@Configuration
@EnableSwagger2 // 标记项目启用 Swagger API 接口文档
public class SwaggerConfiguration {

@Bean
public Docket createRestApi() {
    // 创建 Docket 对象
    return new Docket(DocumentationType.SWAGGER_2) // 文档类型，使用 Swagger2
            .apiInfo(this.apiInfo()) // 设置 API 信息
            // 扫描 Controller 包路径，获得 API 接口
            .select()
            .apis(RequestHandlerSelectors.basePackage("cn.iocoder.springboot.lab24.apidoc.controller"))
            .paths(PathSelectors.any())
            // 构建出 Docket 对象
            .build();
}

/**
 * 创建 API 信息
 */
private ApiInfo apiInfo() {
    return new ApiInfoBuilder()
            .title("测试接口文档示例")
            .description("我是一段描述")
            .version("1.0.0") // 版本号
            .contact(new Contact("芋艿", "http://www.iocoder.cn", "[email protected]")) // 联系人
            .build();
}

}
在类上，添加 @EnableSwagger2 注解， 标记项目启用 Swagger API 接口文档。
通过 #createRestApi() 方法，创建 Swagger Docket Bean 。每个属性的作用，胖友看看艿艿的注释。大多数情况下，胖友使用这些属性是足够的。不过如果想看看其它配置，胖友可以自己去如下两个类翻翻：
Docket.java
ApiInfo.java
2.3 Application
创建 Application.java 类，配置 @SpringBootApplication 注解即可。代码如下：
// Application.java

@SpringBootApplication
public class Application {

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

}
先暂时不启动项目。等我们添加好 Controller 。
2.4 UserController
在 cn.iocoder.springboot.lab24.apidoc.controller 包路径下，创建 UserController 类，提供用户 API 接口。代码如下：
// UserController.java

@RestController
@RequestMapping("/users")
@Api(tags = “用户 API 接口”)
public class UserController {

@GetMapping("/list")
@ApiOperation(value = "查询用户列表", notes = "目前仅仅是作为测试，所以返回用户全列表")
public List<UserVO> list() {
    // 查询列表
    List<UserVO> result = new ArrayList<>();
    result.add(new UserVO().setId(1).setUsername("yudaoyuanma"));
    result.add(new UserVO().setId(2).setUsername("woshiyutou