文章目录
一、Swagger 简介
OpenAPI 规范(以前称为 Swagger 规范)是 REST API的API 描述格式。OpenAPI 文件可以描述整个 API,包括:
1)可用端点 ( /users) 和每个端点上的操作 ( GET /users, POST /users)
2)操作参数 每个操作的输入和输出
3)身份验证方法
4)联系信息、许可、使用条款和其他信息
API 规范可以用 YAML 或 JSON 编写
Swagger 是一个规范且完整的框架,用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。主要的 Swagger 工具包括:
1)Swagger Editor – 基于浏览器的编辑器,可以在其中编写 OpenAPI 规范
2)Swagger UI – 将 OpenAPI 规范呈现为交互式 API 文档
3)Swagger Codegen – 从 OpenAPI 规范生成服务器存根和客户端库
支持 API 自动生成同步的在线文档:使用 Swagger 后可以直接通过代码生成文档,不再需要自己手动编写接口文档了,对程序员来说非常方便,可以节约写文档的时间去学习新技术
提供 Web 页面在线测试 API:Swagger 生成的文档支持在线测试。参数和格式都定好了,直接在界面上输入参数对应的值即
可在线测试接口
二、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 库,用于注释和模型)
1)将前后端有效分离,并保证了API与文档的实时同步
2)使用springfox生成的接口文档直观可视,支持查看各个接口需要的参数和返回结果
3)springfox支持在线测试,可实时检查参数和返回值
接下来主要以v2版本为主。
三、Springfox2.9.2 常用注解
作用:标记类,控制整个类生成接口信息的内容,通常写在MVC中的控制器类上。
常用参数说明:
- tags,类的名称,可以有多个值,定义几个别名,在UI视图中就会显示几个控制器访问菜单
- description,描述,已过时
使用案例:
@RestController
@RequestMapping("/user")
@Api(tags = {
"用户控制层"}, description = "描述被弃用了,但依然可以使用")
public class UserController{
...
}
作用:标记方法,将方法显示到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());
}
作用:描述参数,作用于方法中的参数,将参数的描述显示到文档中
常用参数说明:
- 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());
}
作用:忽略,当前注解描述的方法或类型,不生成API帮助文档
使用案例:
@ApiIgnore
@ApiOperation(value = "用户注册", httpMethod = "POST")
@PostMapping("/register")
public R<User> register(@ApiParam(name="用户(user)", value = "注册的用户信息") User user){
...
}
作用:作用于@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){
...
}