首先,我们必须要有API文档,其次,API文档不能乱。但是怎么做?有人会想到规范化,是的,规范化可以解决多端多系统多版本多人开发下的很多繁杂的问题。因此,OpenAPI Specification就诞生了。
OAS
OAS是OpenAPI Specification的简称,可以翻译为OpenAPI规范,它是定义API的一种规范,它的前身是Swagger规范。
Version2.0
Version3.0.2
可以看出,在2.0版本的时候OAS还冠有Swagger的印记,到了3.0版本就彻底去除了该释义。
OAS定义了一种书写API的一种格式,大家通过遵从同一种格式规范达到API文档的统一。狭义上理解,它用于描述一整套API接口,包括一个接口是GET还是POST请求啊,有哪些参数哪些header等等,它在设计的时候通常是YAML格式,这种格式书写起来比较方便,而在网络中传输时又会以json形式居多,因为json的通用性比较强。OpenAPI Specification已经在2015年捐献给了Linux基金会,现在已经成为RESTful API的世界标准。
Swagger
Swagger是一个工具、一个项目、一个流行的API开发框架(当然,我们上面也说了Swagger是规范,但是后面演变成了OAS),这个框架以OAS为基础,对整个API的开发周期都提供了相应的解决方案,是一个非常庞大的项目(包括Swagger Editor、Swagger UI、Swagger Codegen、Swagger Inspector)。
Swagger官网展示
Github项目
组件 | 作用 |
---|---|
Swagger Editor | REST APIs文档生成工具 |
Swagger Codegen | 根据编辑完成的Swagger API文档文件生成代码的工具 |
Swagger UI | API文档可视化工具 |
Swagger Inspector | API测试工具 |
Springfox
Springfox是践行OAS的一个项目,它将Swagger融合进流行的Spring框架,根据OpenAPI规范,帮助开发者自动生成API文档。Springfox是由Marty Pitt创建的项目swagger-springmvc发展而来。它其中有一个组件叫springfox-swagger2,springfox-swagger2是依赖OSA规范文档,也就是一个描述API的json文件,而这个组件的功能就是帮助我们自动生成这个json文件,我们会用到的另外一个组件springfox-swagger-ui就是将这个json文件解析出来,用一种更友好的方式呈现出来。
总结
现在让我们来总结一下。首先有人定义了一个API文档产生的规范,前期叫Swagger,后面贡献给了Linux基金会,逐渐演变成OpenAPI Specification,逐渐成为世界级别的规范,即OAS,它定义了一种JSON格式或者YAML格式的API文档文件格式;而Swagger提供了Swagger Editor来帮助开发人员熟悉和编写正确的符合OpenAPI规范的API文档文件,这个文件可以使JSON格式的,也可以是YAML格式的;Swagger又提供了Swagger Codegen来生成API文档对应的代码,Swagger Codegen来展示API文档,Swagger Inspector来测试API对应的代码;最后Springfox结合Spring与Swagger,帮助开发人员自动生成对应代码的对应API。
后面,博主会专门写一篇SpringBoot集成Springfox的博文,帮助实现API的自动化。
参考:
https://swagger.io/
http://springfox.github.io/springfox/docs/snapshot/
http://www.cnblogs.com/getupmorning/p/7267076.html
http://springfox.github.io/springfox/
https://petstore.swagger.io/
https://editor.swagger.io/
https://www.jianshu.com/p/cdb41c9e52e2
https://github.com/swagger-api
https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md