SpringBoot - Swagger2的集成与使用教程（生成API接口文档）

超、凢脫俗 2023-01-04 14:30 157阅读 0赞

# SpringBoot - Swagger2的集成与使用教程（生成API接口文档） #

在前后端分离开发中，为了减少与其它团队的沟通成本，一般都会构建一份 RESTful API 文档来描述所有的接口信息。但传统的方式有许多弊端，不仅编写文档工作量巨大，而且维护不方便，测试也不方便（需要借助第三方工具，如 Postman 来测试）

为解决这些问题，我们可以使用 Swagger 2 来构建在线接口文档，下面通过样例进行演示。

## 一、基本介绍 ##

### 1，什么是 Swagger 2 ###

Swagger 2 是一个开源软件框架，可以帮助开发人员设计、构建、记录和使用 RESTful Web 服务，它将代码和文档融为一体，可以完美解决文档编写繁琐、维护不方便等问题。使得开发人员可以将大部分精力集中到业务中，而不是繁杂琐碎的文档中。

### 2，安装配置 ###

（1）首先编辑项目的 pom.xml 文件，添加 Swagger 2 相关依赖：

注意：因为我这里引入的 swagger ui 是 2.7 以上的版本，所以还需要引入 guava，否则会因为 guava 兼容性问题造成项目启动报错（无法启动）

<table> 
 <tbody> 
 <tr> 
 <td> 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 </td> 
 <td> <code>&lt;</code><code>dependency</code><code>&gt;</code> <code>&nbsp;&nbsp;&nbsp;&nbsp;</code><code>&lt;</code><code>groupId</code><code>&gt;io.springfox&lt;/</code><code>groupId</code><code>&gt;</code> <code>&nbsp;&nbsp;&nbsp;&nbsp;</code><code>&lt;</code><code>artifactId</code><code>&gt;springfox-swagger2&lt;/</code><code>artifactId</code><code>&gt;</code> <code>&nbsp;&nbsp;&nbsp;&nbsp;</code><code>&lt;</code><code>version</code><code>&gt;2.9.2&lt;/</code><code>version</code><code>&gt;</code> <code>&lt;/</code><code>dependency</code><code>&gt;</code> <code>&lt;</code><code>dependency</code><code>&gt;</code> <code>&nbsp;&nbsp;&nbsp;&nbsp;</code><code>&lt;</code><code>groupId</code><code>&gt;io.springfox&lt;/</code><code>groupId</code><code>&gt;</code> <code>&nbsp;&nbsp;&nbsp;&nbsp;</code><code>&lt;</code><code>artifactId</code><code>&gt;springfox-swagger-ui&lt;/</code><code>artifactId</code><code>&gt;</code> <code>&nbsp;&nbsp;&nbsp;&nbsp;</code><code>&lt;</code><code>version</code><code>&gt;2.9.2&lt;/</code><code>version</code><code>&gt;</code> <code>&lt;/</code><code>dependency</code><code>&gt;</code> <code>&lt;</code><code>dependency</code><code>&gt;</code> <code>&nbsp;&nbsp;&nbsp;&nbsp;</code><code>&lt;</code><code>groupId</code><code>&gt;com.google.guava&lt;/</code><code>groupId</code><code>&gt;</code> <code>&nbsp;&nbsp;&nbsp;&nbsp;</code><code>&lt;</code><code>artifactId</code><code>&gt;guava&lt;/</code><code>artifactId</code><code>&gt;</code> <code>&nbsp;&nbsp;&nbsp;&nbsp;</code><code>&lt;</code><code>version</code><code>&gt;20.0&lt;/</code><code>version</code><code>&gt;</code> <code>&lt;/</code><code>dependency</code><code>&gt;</code> </td> 
 </tr> 
 </tbody> 
</table>

（2）接着创建 Swagger 2 的配置类，代码如下： 代码说明：

*  首先通过 @EnableSwagger2 注解开启了 Swagger 2，然后最主要的是配置一个 Docket。
 *  通过 apis 方法配置要扫描的 controller 位置，通过 paths 方法配置路径。
 *  在 apiInfo 中构建文档的基本信息，例如描述、联系人信息、版本、标题等。

## 二、使用样例 ##

### 1，添加注解 ###

（1）首先我们在 Controller 上添加相关的 @Api 注解：

（1）@Api 注解标注在类上用来描述整个 Controller 信息。  
（2）@ApiOperation 注解标注在方法上，用来描述一个方法的基本信息。  
（3）@ApiImplicitParam 注解标注在方法上，用来描述方法的参数。其中 paramType 是指方法参数的类型，有如下可选值：

*  path：参数获取方式为 @PathVariable
 *  query：参数获取方式为 @RequestParam
 *  header：参数获取方式为 @RequestHeader
 *  body
 *  form

（4）如果有多个参数，可以将多个参数的 @ApiImplicitParam 注解放到 @ApiImplicitParams 中。  
（5）@ApiResponse 是对响应结果的描述。code 表示响应码，message 为相应的描述信息。如果有多个 @ApiResponse，则放在一个 @ApiResponses 中。  
（6）@ApiIgnore 注解表示不对某个接口生成文档。

<table> 
 <tbody> 
 <tr> 
 <td> 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 </td> 
 <td> <code>@RestController</code> <code>@Api</code><code>(tags = </code><code>"用户数据接口"</code><code>)</code> <code>public</code> <code>class</code> <code>UserController { </code> <code>&nbsp;&nbsp;&nbsp;&nbsp;</code><code>@ApiOperation</code><code>(value =</code><code>"查询用户"</code><code>, notes = </code><code>"根据 id 查询用户"</code><code>)</code> <code>&nbsp;&nbsp;&nbsp;&nbsp;</code><code>@ApiImplicitParam</code><code>(paramType = </code><code>"path"</code><code>, name = </code><code>"id"</code><code>, value = </code><code>"用户 id"</code><code>, required = </code><code>true</code><code>)</code> <code>&nbsp;&nbsp;&nbsp;&nbsp;</code><code>@GetMapping</code><code>(</code><code>"/user/{id}"</code><code>)</code> <code>&nbsp;&nbsp;&nbsp;&nbsp;</code><code>public</code> <code>String getUserById(</code><code>@PathVariable</code> <code>Integer id){ </code> <code>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</code><code>return</code> <code>"查找的用户id是："</code> <code>+ id;</code> <code>&nbsp;&nbsp;&nbsp;&nbsp;</code><code>}</code> &nbsp; <code>&nbsp;&nbsp;&nbsp;&nbsp;</code><code>@ApiOperation</code><code>(value = </code><code>"新增用户"</code><code>, notes = </code><code>"根据传入的用户名和密码添加一个新用户"</code><code>)</code> <code>&nbsp;&nbsp;&nbsp;&nbsp;</code><code>@ApiImplicitParams</code><code>({ </code> <code>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</code><code>@ApiImplicitParam</code><code>(paramType = </code><code>"query"</code><code>, name = </code><code>"username"</code><code>,</code> <code>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</code><code>value = </code><code>"用户名"</code><code>, required = </code><code>true</code><code>, defaultValue = </code><code>"test"</code><code>),</code> <code>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</code><code>@ApiImplicitParam</code><code>(paramType = </code><code>"query"</code><code>, name = </code><code>"password"</code><code>,</code> <code>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</code><code>value = </code><code>"密码"</code><code>, required = </code><code>true</code><code>, defaultValue = </code><code>"123"</code><code>)</code> <code>&nbsp;&nbsp;&nbsp;&nbsp;</code><code>})</code> <code>&nbsp;&nbsp;&nbsp;&nbsp;</code><code>@PostMapping</code><code>(</code><code>"/user"</code><code>)</code> <code>&nbsp;&nbsp;&nbsp;&nbsp;</code><code>public</code> <code>String addUser(</code><code>@RequestParam</code> <code>String username, </code><code>@RequestParam</code> <code>String password) { </code> <code>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</code><code>return</code> <code>"新增用户："</code> <code>+ username + </code><code>" "</code> <code>+ password;</code> <code>&nbsp;&nbsp;&nbsp;&nbsp;</code><code>}</code> &nbsp; <code>&nbsp;&nbsp;&nbsp;&nbsp;</code><code>@ApiOperation</code><code>(value = </code><code>"删除用户"</code><code>, notes = </code><code>"根据 id 删除用户"</code><code>)</code> <code>&nbsp;&nbsp;&nbsp;&nbsp;</code><code>@ApiResponses</code><code>({ </code> <code>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</code><code>@ApiResponse</code><code>(code = </code><code>200</code><code>, message = </code><code>"删除成功！"</code><code>),</code> <code>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</code><code>@ApiResponse</code><code>(code = </code><code>500</code><code>, message = </code><code>"删除失败！"</code><code>)</code> <code>&nbsp;&nbsp;&nbsp;&nbsp;</code><code>})</code> <code>&nbsp;&nbsp;&nbsp;&nbsp;</code><code>@DeleteMapping</code><code>(</code><code>"/user/{id}"</code><code>)</code> <code>&nbsp;&nbsp;&nbsp;&nbsp;</code><code>public</code> <code>Integer deleteUserById(</code><code>@PathVariable</code> <code>Integer id) { </code> <code>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</code><code>return</code> <code>id;</code> <code>&nbsp;&nbsp;&nbsp;&nbsp;</code><code>}</code> &nbsp; <code>&nbsp;&nbsp;&nbsp;&nbsp;</code><code>@ApiOperation</code><code>(value = </code><code>"修改用户"</code><code>, notes = </code><code>"传入用户信息进行更新修改"</code><code>)</code> <code>&nbsp;&nbsp;&nbsp;&nbsp;</code><code>@PutMapping</code><code>(</code><code>"/user"</code><code>)</code> <code>&nbsp;&nbsp;&nbsp;&nbsp;</code><code>public</code> <code>String updateUser(</code><code>@RequestBody</code> <code>User user){ </code> <code>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</code><code>return</code> <code>user.toString();</code> <code>&nbsp;&nbsp;&nbsp;&nbsp;</code><code>}</code> &nbsp; <code>&nbsp;&nbsp;&nbsp;&nbsp;</code><code>@ApiIgnore</code> <code>&nbsp;&nbsp;&nbsp;&nbsp;</code><code>@GetMapping</code><code>(</code><code>"/user/test"</code><code>)</code> <code>&nbsp;&nbsp;&nbsp;&nbsp;</code><code>public</code> <code>String test() { </code> <code>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</code><code>return</code> <code>"这是一个测试接口，不需要在api文档中显示。"</code><code>;</code> <code>&nbsp;&nbsp;&nbsp;&nbsp;</code><code>}</code> <code>}</code> </td> 
 </tr> 
 </tbody> 
</table>

（2）接着对模型对象也添加相关的注解：

由于在上面 Controller 里的 updateUser 方法中，使用 @RequestBody 注解来接收数据，此时可以通过 @ApiModel 注解和 @ApiModelProperty 注解配置 User 对象的描述信息。

<table> 
 <tbody> 
 <tr> 
 <td> 1 2 3 4 5 6 7 8 9 10 11 12 13 14 </td> 
 <td> <code>@Getter</code> <code>@Setter</code> <code>@ToString</code> <code>@ApiModel</code><code>(value = </code><code>"用户实体类"</code><code>, description = </code><code>"用户信息描述类"</code><code>)</code> <code>public</code> <code>class</code> <code>User { </code> <code>&nbsp;&nbsp;&nbsp;&nbsp;</code><code>@ApiModelProperty</code><code>(value = </code><code>"用户id"</code><code>)</code> <code>&nbsp;&nbsp;&nbsp;&nbsp;</code><code>private</code> <code>Integer id;</code> &nbsp; <code>&nbsp;&nbsp;&nbsp;&nbsp;</code><code>@ApiModelProperty</code><code>(value = </code><code>"用户名"</code><code>)</code> <code>&nbsp;&nbsp;&nbsp;&nbsp;</code><code>private</code> <code>String username;</code> &nbsp; <code>&nbsp;&nbsp;&nbsp;&nbsp;</code><code>@ApiModelProperty</code><code>(value = </code><code>"用户密码"</code><code>)</code> <code>&nbsp;&nbsp;&nbsp;&nbsp;</code><code>private</code> <code>String password;</code> <code>}</code> </td> 
 </tr> 
 </tbody> 
</table>

### 2，查看接口文档 ###

（1）启动 Spring Boot 项目，在浏览器中输入 [http://localhost:8080/swagger-ui.html][http_localhost_8080_swagger-ui.html] 即可看到接口文档。

[![原文:SpringBoot - Swagger2的集成与使用教程（生成API接口文档）][SpringBoot - Swagger2_API]][SpringBoot - Swagger2_API_SpringBoot - Swagger2_API]

（2）展开任意一个接口描述，单击 Try it out 按钮后，可以实现对该接口的测试。

![watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3l1Y2FpZnUxOTg5_size_16_color_FFFFFF_t_70][]

## 附：使用 swagger-bootstrap-ui 代替原来的 ui ##

（1）如果觉得原先使用的 swagger ui 比较丑、或者不方便的话，可以试试 swagger-bootstrap-ui。只需修改 pom.xml 文件，将原来的 springfox-swagger-ui 依赖替换成  swagger-bootstrap-ui 即可。

注意：1.9.6 是 swagger-bootstrap-ui 的最后一个版本。由于各种原因，原作者又另起一新的项目：knife4j-spring-ui。knife4j 会包含 swagger-bootstrap-ui 的所有特性，并增加许多新特性，有兴趣的小伙伴可以尝试一下。

<table> 
 <tbody> 
 <tr> 
 <td> 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 </td> 
 <td> <code>&lt;</code><code>dependency</code><code>&gt;</code> <code>&nbsp;&nbsp;&nbsp;&nbsp;</code><code>&lt;</code><code>groupId</code><code>&gt;io.springfox&lt;/</code><code>groupId</code><code>&gt;</code> <code>&nbsp;&nbsp;&nbsp;&nbsp;</code><code>&lt;</code><code>artifactId</code><code>&gt;springfox-swagger2&lt;/</code><code>artifactId</code><code>&gt;</code> <code>&nbsp;&nbsp;&nbsp;&nbsp;</code><code>&lt;</code><code>version</code><code>&gt;2.9.2&lt;/</code><code>version</code><code>&gt;</code> <code>&lt;/</code><code>dependency</code><code>&gt;</code> <code>&lt;</code><code>dependency</code><code>&gt;</code> <code>&nbsp;&nbsp;&nbsp;&nbsp;</code><code>&lt;</code><code>groupId</code><code>&gt;com.github.xiaoymin&lt;/</code><code>groupId</code><code>&gt;</code> <code>&nbsp;&nbsp;&nbsp;&nbsp;</code><code>&lt;</code><code>artifactId</code><code>&gt;swagger-bootstrap-ui&lt;/</code><code>artifactId</code><code>&gt;</code> <code>&nbsp;&nbsp;&nbsp;&nbsp;</code><code>&lt;</code><code>version</code><code>&gt;1.9.6&lt;/</code><code>version</code><code>&gt;</code> <code>&lt;/</code><code>dependency</code><code>&gt;</code> <code>&lt;</code><code>dependency</code><code>&gt;</code> <code>&nbsp;&nbsp;&nbsp;&nbsp;</code><code>&lt;</code><code>groupId</code><code>&gt;com.google.guava&lt;/</code><code>groupId</code><code>&gt;</code> <code>&nbsp;&nbsp;&nbsp;&nbsp;</code><code>&lt;</code><code>artifactId</code><code>&gt;guava&lt;/</code><code>artifactId</code><code>&gt;</code> <code>&nbsp;&nbsp;&nbsp;&nbsp;</code><code>&lt;</code><code>version</code><code>&gt;20.0&lt;/</code><code>version</code><code>&gt;</code> <code>&lt;/</code><code>dependency</code><code>&gt;</code> </td> 
 </tr> 
 </tbody> 
</table>

（2）项目启动后，通过 [http://localhost:8080/doc.html][http_localhost_8080_doc.html] 地址即可访问新的 UI 界面：

[![原文:SpringBoot - Swagger2的集成与使用教程（生成API接口文档）][SpringBoot - Swagger2_API 1]][SpringBoot - Swagger2_API_SpringBoot - Swagger2_API]

（3）可以看到 bootstrap 风格的界面样式比原先的清爽、高效许多：

[http_localhost_8080_swagger-ui.html]: http://localhost:8080/swagger-ui.html
[SpringBoot - Swagger2_API]: https://img-blog.csdnimg.cn/img_convert/583618378845df1f586823298fc10466.png
[SpringBoot - Swagger2_API_SpringBoot - Swagger2_API]: /images/20221119/0ae606e3e6cb413f85d412b61a12197c.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3l1Y2FpZnUxOTg5_size_16_color_FFFFFF_t_70]: /images/20221119/3e491e3fa1fc440eb9d15a62983384e3.png
[http_localhost_8080_doc.html]: http://localhost:8080/doc.html
[SpringBoot - Swagger2_API 1]: https://img-blog.csdnimg.cn/img_convert/57b06f18ea7dadca80c265ef710d5c16.png