一, 传统方式
众所周知, 我们 Java 程序员在写完数据接口之后, 想要前端或者 App 工程师调用的, 需要写出接口文档, 方便描述每一个接口都是干什么的, 需要什么, 怎么请求, 返回的结果又是什么? 可是现在的你是否还在手写接口文档呢? 在手写接口文档中, 有没有遇到, 文档刚写好, 测试反馈接口有问题, 又不得不改写接口, 结果接口改完之后, 发送文档对不上了, 怎么办?
我在工作中, 是如何编写接口文档的呢? 接下来给大家聊一神器, 惊喜在后面.
首先, 我新建一个项目, 基于 Spring Boot, 开发几个接口, 发布运行.
编写代码, 实现 2 个数据接口, 一个 Post 请求, 新增, 一个 Get 请求实现查询
运行项目, 并测试接口
按照传统方式, 项目写完了是不是要写接口文档? 传统的接口文档就是如下所示:
接口: 用户数据查询
地址: http://localhost:8080/user/all.do
请求方式: GET
请求参数: 无
返回格式: JSON
返回数据参考:
二, Swagger
可是现在突然接口发生了变化? 怎么办? 是不是要去改动接口, 再来改动文档? 那么今天咱们用 Swagger 来接口数据接口改动对接口文档的影响.
Swagger 最受欢迎的 REST APIs 文档生成工具之一, 可以生成一个具有互动性的 API 控制台, 开发者可以用来快速学习和测试 API.
那么 Swagger 如何应用? 接下来三部曲:
1, 依赖 jar
2, 配置注解
在对应的数据接口上使用以下注解:
@API 修饰类 标记这个类是做什么的
@ApiOption 修饰方法, 标记这个映射方法是解决什么问题的
3, 启用 Swagger
在 SpringBoot 的开关类上使用注解 @EnableSwagger2
重新运行项目, 在浏览器访问 swagger-ui.html 页面, 可以看到如下内容:
我们可以看到刚刚咱们写的 2 个接口, 请求方式, 路径, 做什么的是不是都可以清晰的看到? 那么我们再来进行下面的测试接口:
三, 总结
其实 Swagger 重要的 2 个作用: 1, 显示目前项目的所有数据接口信息包含路径, 参数, 返回格式, 数据模型, 2 可以进行在线接口测试, 完美解决后端工程师的难题, 你会了吗?
来源: http://www.bubuko.com/infodetail-3068906.html