Spring Boot API 接口文档 Swagger 入门（上）

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

1. 概述

目前，大多数系统都采用前后端分离。在享受前后端分离的好处的同时，接口联调往往成为团队效率的瓶颈，甚至产生前后端的矛盾。简单归结来说，有几方面的原因：

• 问题一，接口设计滞后。 后端团队往往不喜欢 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 文件中，引入相关依赖。

            org.springframework.boot        spring-boot-starter-parent        2.1.3.RELEASE                 4.0.0    lab-24-apidoc-swagger                                org.springframework.boot            spring-boot-starter-web                                    io.springfox            springfox-swagger2            2.9.2                                    io.springfox            springfox-swagger-ui            2.9.2            

具体每个依赖的作用，胖友自己认真看下艿艿添加的所有注释噢。

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@SpringBootApplicationpublic 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 list() {        // 查询列表        List result = new ArrayList<>();        result.add(new UserVO().setId(1).setUsername("yudaoyuanma"));        result.add(new UserVO().setId(2).setUsername("woshiyutou"));        result.add(new UserVO().setId(3).setUsername("chifanshuijiao"));        // 返回列表        return result;    }    @GetMapping("/get")    @ApiOperation("获得指定用户编号的用户")    @ApiImplicitParam(name = "id", value = "用户编号", paramType = "query", dataTypeClass = Integer.class, required = true, example = "1024")    public UserVO get(@RequestParam("id") Integer id) {        // 查询并返回用户        return new UserVO().setId(id).setUsername(UUID.randomUUID().toString());    }    @PostMapping("add")    @ApiOperation("添加用户")    public Integer add(UserAddDTO addDTO) {        // 插入用户记录，返回编号        Integer returnId = UUID.randomUUID().hashCode();        // 返回用户编号        return returnId;    }    @PostMapping("/update")    @ApiOperation("更新指定用户编号的用户")    public Boolean update(UserUpdateDTO updateDTO) {        // 更新用户记录        Boolean success = true;        // 返回更新是否成功        return success;    }    @PostMapping("/delete")    @ApiOperation(value = "删除指定用户编号的用户")    @ApiImplicitParam(name = "id", value = "用户编号", paramType = "query", dataTypeClass = Integer.class, required = true, example = "1024")    public Boolean delete(@RequestParam("id") Integer id) {        // 删除用户记录        Boolean success = false;        // 返回是否更新成功        return success;    }}

• 相比我们之前使用 SpringMVC 来说，我们在类和接口上，额外增加了 Swagger 提供的注解。
• 从使用习惯上，我比较喜欢先添加 SpringMVC 的注解，再添加 Swagger 的注解。
• 因为已经使用了 Swagger 的注解，所以类和方法上的注释，一般可以删除了，除非有特殊诉求。
• 其中涉及到的 POJO 类，有 UserAddDTO、UserUpdateDTO、UserVO 。

执行 Application 启动项目。然后浏览器访问 http://127.0.0.1:8080/swagger-ui.html地址，就可以看到 Swagger 生成的 API 接口文档。如下图所示：

至此，我们已经完成了 Swagger 的快速入门。不过考虑到胖友能够更好的使用，我们来一个一个注解了解。

2.5 注解

在 swagger-annotations 库中，在 io.swagger.annotations 包路径下，提供了我们会使用到的所有 Swagger 注解。Swagger 提供的注解还是比较多的，大多数场景下，只需要使用到我们在 「2.4 UserController」 中用到的注解。

2.5.1 @Api

@Api 注解，添加在 Controller 类上，标记它作为 Swagger 文档资源。

示例如下：

// UserController.java@RestController@RequestMapping("/users")@Api(tags = "用户 API 接口")public class UserController {    // ... 省略}

效果如下：

@Api 注解的常用属性，如下：

• tags 属性：用于控制 API 所属的标签列表。[] 数组，可以填写多个。
• 可以在一个 Controller 上的 @Api 的 tags 属性，设置多个标签，那么这个 Controller 下的 API 接口，就会出现在这两个标签中。
• 如果在多个 Controller 上的 @Api 的 tags 属性，设置一个标签，那么这些 Controller 下的 API 接口，仅会出现在这一个标签中。
• 本质上，tags 就是为了分组 API 接口，和 Controller 本质上是一个目的。所以绝大数场景下，我们只会给一个 Controller 一个唯一的标签。例如说，UserController 的 tags 设置为 "用户 API 接口" 。

@Api 注解的不常用属性，如下：

• produces 属性：请求请求头的可接受类型( Accept )。如果有多个，使用 , 分隔。
• consumes 属性：请求请求头的提交内容类型( Content-Type )。如果有多个，使用 ,分隔。
• protocols 属性：协议，可选值为 "http"、"https"、"ws"、"wss" 。如果有多个，使用 , 分隔。
• authorizations 属性：授权相关的配置，[] 数组，使用 @Authorization 注解。
• hidden 属性：是否隐藏，不再 API 接口文档中显示。

@Api 注解的废弃属性，不建议使用，有value、description、basePath、position 。

2.5.2 @ApiOperation

@ApiOperation 注解，添加在 Controller 方法上，标记它是一个 API 操作。

示例如下：

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

效果如下：

@ApiOperation 注解的常用属性，如下：

• value 属性：API 操作名。
• notes 属性：API 操作的描述。

@ApiOperation 注解的不常用属性，如下：

• tags 属性：和 @API 注解的 tags 属性一致。
• nickname 属性：API 操作接口的唯一标识，主要用于和第三方工具做对接。
• httpMethod 属性：请求方法，可选值为 GET、HEAD、POST、PUT、DELETE、OPTIONS、PATCH 。因为 Swagger 会解析 SpringMVC 的注解，所以一般无需填写。
• produces 属性：和 @API 注解的 produces 属性一致。
• consumes 属性：和 @API 注解的 consumes 属性一致。
• protocols 属性：和 @API 注解的 protocols 属性一致。
• authorizations 属性：和 @API 注解的 authorizations 属性一致。
• hidden 属性：和 @API 注解的 hidden 属性一致。
• response 属性：响应结果类型。因为 Swagger 会解析方法的返回类型，所以一般无需填写。
• responseContainer 属性：响应结果的容器，可选值为 List、Set、Map 。
• responseReference 属性：指定对响应类型的引用。这个引用可以是本地，也可以是远程。并且，当设置了它时，会覆盖 response 属性。说人话，就是可以忽略这个属性，哈哈哈。
• responseHeaders 属性：响应头，[] 数组，使用 @ResponseHeader 注解。
• code 属性：响应状态码，默认为 200 。
• extensions 属性：拓展属性，[] 属性，使用 @Extension 注解。
• ignoreJsonView 属性：在解析操作和类型，忽略 JsonView 注释。主要是为了向后兼容。

@ApiOperation 注解的废弃属性，不建议使用，有 position 。