OpenAPI简介
API（Application Programming Interface）
API 这个词，百度百科的解释如下：
API（应用程序编程接口）是一些预先定义的函数，目的是提供应用程序与开发人员基于某软件或硬件得以访问一组例程的能力，而又无需访问源码，或理解内部工作机制的细节。
API 有很多种, 简单划分可以分为操作系统级API, 库与框架的API和Web API等等。
OpenAPI属于Web API的一种, 它们不是一个具体的编程语言函数，而是一个个 http 请求。我们经常使用的微信公众号, 地图服务, 导航服务等等, 都会提供一套API供广大开发者调用, 从而可以利用这些基础API开发出更加强大的APP。
OpenAPI规范
OpenAPI 规范 (OAS) ，是一个定义
标准的、与具体编程语言无关的RESTful API的规范。本规范使得人类和计算机都能在“不接触任何程序源代码和文档、不监控网络通信”的情况下理解一个服务的作用。一个良好定义的 API 可以使得使用者非常轻松地理解并与之交互而不需要了解它的实现逻辑。
完整的OpenAPI规范定义可以在GitHub上找到：
- OpenAPI V1.2
- OpenAPI V2.0
- OpenAPI V3.0
- OpenAPI V3.1
中文版:
- OpenAPI V3.0.0
中英文对照版:
- OpenAPI V3.0.3(翻译进行中)
Swagger简介
提到OpenAPI, 就不得不提Swagger, 因为Swagger规范就是OpenAPI规范的前身, 从3.0开始才改名为OpenAPI规范。通常所说的 Swagger 是指由SmartBear公司维护的一套围绕OpenAPI规范构建的开源工具，可以帮助您设计，构建，编写和使用REST API。
常用的Swagger工具包括：
- Swagger Editor : 基于浏览器的编辑器，您可以在其中编写OpenAPI规范。
- Swagger UI : 将OpenAPI规范呈现为交互式API文档。
- Swagger Codegen : 根据OpenAPI规范生成服务器存根和客户端库。
除了以上列出来的常用工具外, 官网 上还有大量的其他工具和资源, 有兴趣的读者可以到 官网 上去围观。
wapache-openapi简介
wapache-openapi 是本文作者创建的一个项目, 它整合了openapi spec, swagger-api, springdoc, rapidoc, openapi-generator等多个开源项目, 提供Spring集成, 代码生成和文档生成, 可视化展示等功能的整合, 在众多开源项目基础上针对中文环境和使用习惯做了一定裁剪,扩展和汉化。
目前该项目才刚刚起步, 还有很多需要完善的地方, 欢迎广大开发者参与进来一起完善它。
为什么要使用OpenAPI？
圈内人有时候自嘲会说, 自己是一名API工程师, 意思就是只会调用API, 其他啥都不会的工程师。然而在日常的工作中，调用和调试各种各样的API确实占了很大的一个比例。
有一定开发经验的程序员一定都有以下开发经历:
- 接口文档和实际接口不一致
- 接口晦涩, 难以理解和调试
- 缺少例子, 纯靠自己摸索
- 需要根据API文档编写大量的消息/协议解析的代码, 工作量巨大
- 懒得看文档或者理解不够透彻, 写出来的实现代码漏洞多
而如果您遵循 OpenAPI 规范来定义您的 API，那么您就可以
- 用 文档生成工具 来展示您的 API。
- 用 代码生成工具 来自动生成各种编程语言的服务器端和客户端的代码。
- 用 自动测试工具 进行测试等等。
从而避免上述的5种糟糕的开发体验。
设计优先和编码优先
设计优先(Design-First)
国内大部分公司采用的应该都是这种方式, 首先由架构师或设计人员先设计(一般都是写word文档,描述每个接口的URL, 参数, 返回等等), 然后开发人员根据设计文档编写代码实现功能。
采用OpenAPI规范后, 编写的就不再是Word, 而是OpenAPI文档, 其通常的工作流程如下:
- 使用 Swagger Editor 等工具设计您的API。
- 使用 openapi-generator 或者 Swagger Codegen 为您的API生成服务器存根。
你的API已经准备好了！剩下的唯一要做的事情就是实现服务器逻辑。 - 使用 openapi-generator 或者 Swagger Codegen 为您的API生成超过20种语言的客户端库。
- 使用 Swagger UI 生成交互式API文档，让用户直接在浏览器中尝试API调用。
- 使用该规范将API相关工具连接到您的API。例如，将规范导入到SoapUI来为您的API创建自动化测试。
编码优先(Code-First)：
和设计优先不同, 编码优先顾名思义就是先写文档, 后生成设计文档, 以Java为例:
- 使用 Eclipse 或者 IDEA 等IDE编写API接口代码。
- 使用 springfox 或者 springdoc 等类库实时生成OpenAPI文档。
- 使用 openapi-generator 或者 Swagger Codegen 为您的API生成超过20种语言的客户端库。
- 使用 Swagger UI 生成交互式API文档，让用户直接在浏览器中尝试API调用。
- 使用该规范将API相关工具连接到您的API。例如，将规范导入到SoapUI来为您的API创建自动化测试。
选择设计优先还是编码优先?
这两种开发流程本质上没有谁好谁差之分, 不同的场景下各有优势
如果负责设计的人不熟悉编程语言, 那么建议采用设计优先的方式, 而如果设计者本身对目标开发语言有一定基础, 那么建议使用代码优先方式进行开发, 理由就是减少重复劳动和减少工作量, 代码即文档, 文档和代码高度一致(尤其是多分支多版本情况下优势明显), 支持版本管理。