OAS3和Swagger

面向web api开发
大家在开发完 webapi 后，经常为了方便接口双方对接，需要将 webapi 接口文档化，那有没有什么快捷可交互的文档呢？可以利用快捷工具 swagger，它的可视化 UI 可轻松助你 API 文档化的同时还方便测试 API。 

什么是swagger
swagger 是一个规范且完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。 swagger 的目标是对 REST API 定义一个标准且和语言无关的接口，可以让人和计算机拥有无需访问源码、文档或网络流量监测就可以发现和理解服务的能力。当通过 swagger 进行正确定义，用户可以理解远程服务并使用最少实现逻辑与远程服务进行交互。与为底层编程所实现的接口类似，swagger 消除了调用服务时可能会有的猜测。 

swagger 的优势

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

一句话： swagger的使用，写好注释就是写好接口文档。

什么是OAS3
作为一个经常要提供给API文档给内部和第三方的阅读的“苦程”，我一直在寻找一个完美的Spring MVC文档解决方案。过去，我一直使用的是springfox-swagger2依赖，使用swagger2注解，对代码进行注释，生成swagger文档。 不过，早在2020年swagger2就已过时，springfox-swagger2也已停止维护。业界普遍转向了OAS3 规范管理文档接口，这也是当前OpenApi规范标准。 

可喜的是DELPHI也可以哦。

http://42.193.160.160:8080/rest/app/openapi/

点击上面的链接，即可查看笔者的OAS3在线API文档哦。