Swagger 学习笔记 | Swagger 简介 | Springfox 简介 | Springfox 2.9.2 常用注解 | Spring Boot 整合 Swagger2 案例

一、Swagger 简介

---

OpenAPI 简介

OpenAPI 规范（以前称为 Swagger 规范）是 REST API的API 描述格式。OpenAPI 文件可以描述整个 API，包括：
1）可用端点 ( /users) 和每个端点上的操作 ( GET /users, POST /users)
2）操作参数 每个操作的输入和输出
3）身份验证方法
4）联系信息、许可、使用条款和其他信息
API 规范可以用 YAML 或 JSON 编写

Swagger 简介

Swagger 是一个规范且完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。主要的 Swagger 工具包括：
1）Swagger Editor – 基于浏览器的编辑器，可以在其中编写 OpenAPI 规范
2）Swagger UI – 将 OpenAPI 规范呈现为交互式 API 文档
3）Swagger Codegen – 从 OpenAPI 规范生成服务器存根和客户端库

Swagger 作用

支持 API 自动生成同步的在线文档：使用 Swagger 后可以直接通过代码生成文档，不再需要自己手动编写接口文档了，对程序员来说非常方便，可以节约写文档的时间去学习新技术

提供 Web 页面在线测试 API：Swagger 生成的文档支持在线测试。参数和格式都定好了，直接在界面上输入参数对应的值即
可在线测试接口

二、Springfox 简介

---

Springfox 介绍文章

Springfox 是一个使用Java语言开发开源的API Doc的框架， 它的前身是swagger-springmvc，可以将我们的Controller中的方法以文档的形式展现。官方定义为： Automated JSON API documentation for API’s built with Spring。

Springfox 目前有1、2、3三种版本，从v3版本开始则有较大变化，据官方文档介绍，变化如下：

• 删除早期版本的一些依赖。特别是删除springfox-swagger2和springfox-swagger-ui依赖。

• 删除 @EnableSwagger2 注释

• 添加 springfox-boot-starter 支持springboot使用的起步依赖

• Springfox 3.x 删除了对 guava 和其他第三方库的依赖（但仍然依赖于 spring 插件和开放 api 库，用于注释和模型）

Springfox 的作用

1）将前后端有效分离，并保证了API与文档的实时同步
2）使用springfox生成的接口文档直观可视，支持查看各个接口需要的参数和返回结果
3）springfox支持在线测试，可实时检查参数和返回值

接下来主要以v2版本为主。

三、Springfox2.9.2 常用注解

---

Springfox官方配置文档

@Api

作用：标记类，控制整个类生成接口信息的内容，通常写在MVC中的控制器类上。

常用参数说明：

• tags，类的名称，可以有多个值，定义几个别名，在UI视图中就会显示几个控制器访问菜单
• description，描述，已过时

使用案例：

@RestController
@RequestMapping("/user")
@Api(tags = {
   "用户控制层"}, description = "描述被弃用了，但依然可以使用")
public class UserController{
   
	...
}

@ApiOperation

作用：标记方法，将方法显示到Swagger生成的文档中

常用参数说明：

• value，方法的名称
• notes，方法的记录
• httpMethod, 请求方式

使用案例：

@ApiOperation(value = "用户注册", httpMethod = "POST")
@PostMapping("/register")
public R<User> register(User user){
   
    return userService.register(user) ?
            R.success("注册成功", user)
                : R.fail("注册失败", new User());
}

@ApiParam

作用：描述参数，作用于方法中的参数，将参数的描述显示到文档中

常用参数说明：

• name，参数名
• value，参数描述
• require， true/false，表示参数是否必要

使用案例：

@ApiOperation(value = "用户注册", httpMethod = "POST")
@PostMapping("/register")
public R<User> register(@ApiParam(name="用户(user)", value = "注册的用户信息") User user){
   
    return userService.register(user) ?
            R.success("注册成功", user)
                : R.fail("注册失败", new User());
}

@ApiIgnore

作用：忽略，当前注解描述的方法或类型，不生成API帮助文档

使用案例：

@ApiIgnore
@ApiOperation(value = "用户注册", httpMethod = "POST")
@PostMapping("/register")
public R<User> register(@ApiParam(name="用户(user)", value = "注册的用户信息") User user){
   
    ...
}

@ApiImplicitParam

作用：作用于@Api类中的方法，用于描述方法中的单个参数

常用参数说明：

• name，参数名，需要与方法中的参数名对应
• value，参数描述
• require， true/false，表示参数是否必要
• dataType，参数类型
  使用案例：

 @ApiOperation(value = "用户注册", httpMethod = "POST")
 @ApiImplicitParam(name = "user", value = "注册的用户信息")
 @PostMapping("/register")
 public R<User> register(@ApiParam(name="用户", value = "注册的用户信息") User user){
   
     ...
 }
</