如何更好管理 Api 接口(续)

2021年11月22日 阅读数:8
这篇文章主要向大家介绍如何更好管理 Api 接口(续),主要内容包括基础应用、实用技巧、原理机制等方面,希望对大家有所帮助。

image.png

哈喽,我是树酱。去年中旬的时候写过一篇关于 如何更好管理 Api 接口。最近有朋友问我,咱们都是根据Swagger文档,而后经过“阅读”swagger文档中每一个微服务包含的CRUD(增刪查改)等API,再经过“手动”撸出各类service文件,以此达到封装的结果。可是这样会暴露一些问题,以下👇
  • 若是接口发生变动,好比接口从v1迁移到v2版本,那须要进行大量的改造
  • 每增长一个项目,我都是须要封装一套service,重复造轮子不亦乐乎?
  • 团队加入新成员,编写重复的接口封装等

那有什么办法能够解决上述的问题?
方法是有的,本质上经过程序自动化去生成各类service文件,解放双手。那具体怎么作呢?咱们能够经过解析swagger接口文档的结构前端

1.什么是 Swagger / OpenAPI ?

在聊解析文档以前,咱们首先须要先了解一下 OpenAPI 👇

image.png

OpenAPI规范,也称做OAS,是一种API文档标准 java

经过 OpenAPI 规范来定义您的 API,您就能够用文档生成工具来展现您的 API,甚至能够使用代码生成工具来自动生成各类编程语言的服务器端和客户端的代码。linux

👧 啊乐同窗:那openAPI与swagger之间有是什么关系?

OpenAPI 始于 Swagger 规范,Swagger 规范已于2015 年捐赠给 Linux 基金会后更名为 OpenAPI,并定义最新的规范为 OpenAPI 3.0ios

本质上你能够理解为前者是规范,后者则是实现规范的工具 👇git

  • OpenAPI = 规范
  • Swagger = 实现规范的工具
👦 啊乐同窗:那么一个经过OpenAPI规范实现的对象是什么样子的呢?

具体主要包括如下这些字段信息(指的是OpenAPI 3.0)github

image.png

若是你想实时预览OpenAPI在线编辑的效果,能够尝试使用 Swagger Editor编程

image.png

👦 啊呆同窗:我看有两种规范,OAS2与OAS3,这两种有什么区别呢?

OAS2是Swagger2的简称,上文提到,自 Swagger 规范捐献给linux以后,将Swagger规范重命名为OpenAPI规范,就是咱们提到的OAS3。下图是二者的区分👇 axios

image.png

推荐阅读:segmentfault

2.如何解析 Swagger / OpenAPI ?

梳理完OpenAPI规范结构,接下来咱们就须要经过解析OpenApi文档结构来生成咱们的service文件

我在社区找到目前的两种解决方式 👇api

2.1 @umijs/plugin-openapi插件

umijs封装了一个openapi插件,经过输入一个 openapi 的规范文件,就能够完成自动化建立service。

这个规范文件咱们在经过swagger-ui的界面中能够获取

image.png

而后把这个复制swagger的url到openapi的配置中(schemaPath参数),能够参考下图👇

image.png

而后执行命令行就能够自动生成如下目录结构serves

image.png

这里以宠物商店的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 种语言及框架)的业务代码,好比接口请求代码

image.png

上图是Apifox的生成代码的界面,这里以TypeScript语言+axios请求库为例,咱们还能够选择咱们导出的代码包含的内容,好比只须要仅接口代码或仅模型等

3.最后

若是你有更好的实现方式,也能够在评论区留言,也能够加我微信,咱们一块儿喝茶🍵 讨论