Swagger是什么？Swagger怎么用？

分手后的思念是犯贱 2024-03-30 09:53 78阅读 0赞

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

Swagger 的目标是对 REST API 定义一个标准且和语言无关的接口，可以让人和计算机拥有无须访问源码、文档或网络流量监测就可以发现和理解服务的能力。当通过 Swagger 进行正确定义，用户可以理解远程服务并使用最少实现逻辑与远程服务进行交互。与为底层编程所实现的接口类似，Swagger 消除了调用服务时可能会有的猜测。

Swagger 的优势

*  支持 API 自动生成同步的在线文档：使用 Swagger 后可以直接通过代码生成文档，不再需要自己手动编写接口文档了，对程序员来说非常方便，可以节约写文档的时间去学习新技术。
 *  提供 Web 页面在线测试 API：光有文档还不够，Swagger 生成的文档还支持在线测试。参数和格式都定好了，直接在界面上输入参数对应的值即可在线测试接口。

### 集成 Swagger 管理 API 文档 ###

1）项目中集成 Swagger

集成 Swagger 我们使用封装好了的 Starter 包，代码如下所示。

> 1.  ``
> 2.  `<dependency>`
> 3.  `<groupId>com.spring4all</groupId>`
> 4.  `<artifactId>swagger-spring-boot-starter</artifactId>`
> 5.  `<version>1.7.1.RELEASE</version>`
> 6.  `</dependency>`

在启动类中使用 @EnableSwagger2Doc 开启 Swagger，代码如下所示。

> 1.  `@EnableSwagger2Doc`
> 2.  `@SpringBootApplication`
> 3.  `public class AuthApplication {`
> 4.  `public static void main(String[] args) {`
> 5.  `SpringApplication.run(AuthApplication.class, args);`
> 6.  `}`
> 7.  `}`

2）使用 Swagger 生成文档

Swagger 是通过注解的方式来生成对应的 API，在接口上我们需要加上各种注解来描述这个接口，关于 Swagger 注解的使用在教程后面会有详细讲解，本节只是带大家快速使用 Swagger，使用方法代码如下所示。

> 1.  `@ApiOperation(value = "新增用户")`
> 2.  `@ApiResponses({ @ApiResponse(code = 200, message = "OK", response = UserDto.class) })`
> 3.  `@PostMapping("/user")`
> 4.  `public UserDto addUser(@RequestBody AddUserParam param) {`
> 5.  `System.err.println(param.getName());`
> 6.  `return new UserDto();`
> 7.  `}`

参数类定义代码如下所示。

> 1.  `@Data`
> 2.  `@ApiModel(value = "com.biancheng.auth.param.AddUserParam", description = "新增用户参数")`
> 3.  `public class AddUserParam {`
> 4.  `@ApiModelProperty(value = "ID")`
> 5.  `private String id;`
> 6.  `@ApiModelProperty(value = "名称")`
> 7.  `private String name;`
> 8.  `@ApiModelProperty(value = "年龄")`
> 9.  `private int age;`
> 10. `}`

### 在线测试接口 ###

接口查看地址可以通过服务地址 /swagger-ui.html 来访问，见图 1。

![5c5483e97d638b1e5d37377b77782b22.png][]

图 1 swagger 主页

可以展开看详情，见图 2。

![3a2437a049f61131c5173f86bd2bce9e.png][]

图 2 swagger 接口主页

在 param 中输入参数，点击 Try it out 按钮可以调用接口，见图 3。

![3deef3c2978b2e27cdb8997ee51668a7.png][]

图 3 swagger 接口调用结果

[5c5483e97d638b1e5d37377b77782b22.png]: https://image.dandelioncloud.cn/pgy_files/images/2024/03/30/6fd752f8b6264d12ac857a94c72999f9.png
[3a2437a049f61131c5173f86bd2bce9e.png]: https://image.dandelioncloud.cn/pgy_files/images/2024/03/30/538618b5463c4413b5804aa2a6cab328.png
[3deef3c2978b2e27cdb8997ee51668a7.png]: https://image.dandelioncloud.cn/pgy_files/images/2024/03/30/a5079e11c7e049d7ad3bceecb9204e84.png