哈喽，我是树酱。去年中旬的时候写过一篇对于如何更好治理 Api 接口。最近有敌人问我，咱们都是依据 Swagger 文档，而后通过“浏览”swagger 文档中每个微服务蕴含的 CRUD(增刪查改)等 API，再通过“手动”撸出各种 service 文件，以此达到封装的后果。然而这样会裸露一些问题，如下👇
- 如果接口产生变更，比方接口从 v1 迁徙到 v2 版本，那须要进行大量的革新
- 每减少一个我的项目，我都是须要封装一套 service，反复造轮子不可开交？
- 团队退出新成员，编写反复的接口封装等
那有什么方法能够解决上述的问题？
办法是有的，实质上通过程序自动化去生成各种 service 文件，解放双手。那具体怎么做呢？咱们能够通过解析 swagger 接口文档的构造
1. 什么是 Swagger / OpenAPI？
在聊解析文档之前，咱们首先须要先理解一下 OpenAPI 👇
OpenAPI 标准，也称作 OAS，是一种 API 文档规范
通过 OpenAPI 标准来定义您的 API，您就能够用文档生成工具来展现您的 API，甚至能够应用代码生成工具来主动生成各种编程语言的服务器端和客户端的代码。
👧 啊乐同学：那 openAPI 与 swagger 之间有是什么关系？
OpenAPI 始于 Swagger 标准，Swagger 标准已于 2015 年捐献给 Linux 基金会 后改名为 OpenAPI，并定义最新的标准为 OpenAPI 3.0
实质上你能够了解为前者是标准，后者则是实现标准的工具 👇
- OpenAPI = 标准
- Swagger = 实现标准的工具
👦 啊乐同学：那么一个通过 OpenAPI 标准实现的对象是什么样子的呢？
具体次要包含以下这些字段信息（指的是 OpenAPI 3.0）
如果你想实时预览 OpenAPI 在线编辑的成果，能够尝试应用 Swagger Editor
👦 啊呆同学：我看有两种标准，OAS2 与 OAS3，这两种有什么区别呢？
OAS2 是 Swagger2 的简称，上文提到，自 Swagger 标准募捐给 linux 之后，将 Swagger 标准重命名为 OpenAPI 标准，就是咱们提到的 OAS3。下图是两者的辨别👇
举荐浏览：
- Apifox – OpenAPI 标准 (中文版)
2. 如何解析 Swagger / OpenAPI？
梳理完 OpenAPI 标准构造，接下来咱们就须要通过解析 OpenApi 文档构造来生成咱们的 service 文件
我在社区找到目前的两种解决形式 👇
2.1 @umijs/plugin-openapi 插件
umijs 封装了一个 openapi 插件，通过输出一个 openapi 的标准文件，就能够实现自动化创立 service。
这个标准文件咱们在通过 swagger-ui 的界面中能够获取
而后把这个复制 swagger 的 url 到 openapi 的配置中（schemaPath 参数），能够参考下图👇
而后执行命令行就能够主动生成以下目录构造 serves
这里以宠物商店的 DEMO API 文档为例，看下生成的接口封装成什么样子
同时在 serves 中咱们也会生成 typings.d.ts 文件，蕴含了 openapi 中的定义
目前该工具的劣势在于，重度绑定了 umi 且对中文反对不敌对。如果你感觉不适宜外部的技术栈，能够参考该工具的实现思路，而后在它的根底上本人造轮子
2.2 本地化工具生成
OpenApi 社区开源了 OpenApi Generator，咱们能够通过
OpenAPI Generator，通过提供 OpenAPI 标准 (上文提到的 OAS2 和 OAS3) 来主动生成 API 客户端库、文档及配置。
比方咱们前端依赖 axios 作为申请库，那么咱们能够通过指定类型来生成 ts+axios 的申请相干的代码
具体应用请查阅 🔗 github – openapi-generator
如果你是前端并且对 java 并不相熟的童鞋，间接应用会收到技术栈限度，因为它提供的是一个 JAR 包，尽管也有提供 cli 工具，然而只反对 yml 格局解析
那么有没有更编辑的形式，能够不依赖环境去应用呢？
这里提供一个工具，不便你间接应用: Apifox
Apifox 不仅反对 mock 性能和接口调试，我发现还有个代码生成性能，代码生成引擎应用的也就是咱们提到的 openapi-generator，能够依据接口 / 模型定义，主动生成各种语言 / 框架（如 TypeScript、Java、Go、Swift 等 130 种语言及框架）的业务代码，比方接口申请代码
上图是 Apifox 的生成代码的界面，这里以 TypeScript 语言 +axios 申请库为例，咱们还能够抉择咱们导出的代码蕴含的内容，比方只须要仅接口代码或仅模型等
3. 最初
如果你有更好的实现形式，也能够在评论区留言，也能够加我微信，咱们一起喝茶🍵 探讨