如何更好管理 Api 接口（续）

哈喽，我是树酱。去年中旬的时候写过一篇关于如何更好管理 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。下图是两者的区分👇

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请求库为例，我们还可以选择我们导出的代码包含的内容，比如只需要仅接口代码或仅模型等