OpenAPI 自动生成接口请求代码
前言
OpenAPI简介
小问题,为什么Java同事只写了一些注解,我们就能看到了swagger文档的定义了呢?答案其实很简单就是OpenAPI规范。
定义
OpenAPI规范又名Swagger规范,最早属于swagger项目的一部分,下面是swaagger对于OpenAPI的定义。
”OpenAPI 规范 (OAS) 为 RESTful API 定义了一个与语言无关的标准接口,它允许人类和计算机在不访问源代码、文档或通过网络流量检查的情况下发现和理解服务的功能。如果定义得当,消费者可以用最少的实现逻辑来理解远程服务并与之交互。“
修订历史
目前用的最多是swagger 2.0版本(以我公司为例)。后续介绍以2.0举例介绍。
规范(Specification)
只列举常用字段,详细字段请参考swagger.io官网
通过上面的介绍我们可以得出一个狭义的通俗说法,openapi(特指swagger.json)本质就是一个用户描述接口信息的json文件。
那么swagger.json已经详细描述接口信息,并且能根据json生成swagger-ui, 那我们是不是能根据swagger.json生成我们跟接口相关的请求、响应声明的typing.d.ts呢,那进一步我们能不能根据一定的规则模板生成我们想要请求代码呢,答案是肯定的,下面章节我们详细讲述怎么通过工具库做到这些。
请求、响应声明
背景
写了挺久的Typescript代码, 除了业务组件外, 对于类型定义最为迫切的其实是接口响应数据。然而根据将swagger的数据结构搬过来转 为type 或 interface的工作量是巨大且繁琐的,所以有时候就会偷懒直接使用了any类型,那这样就违背了使用typecript的初衷。所以内心有个想法就是Java的既然是强类型语言,那是否存在一种场景java数据类型跟typescript数据类型的映射关系,直接将Java的类型直接转为typescript 的数据类型呢,这一搜果然,已经有相关库实现了这个功能。openapi-typescript, 并根据这个库进一步了解了openapi的规范。
实现原理
根据上述的swagger规范,将不同字段转为interface,核心代码是transform目录,根据不同的字段进行转换,底层通过nodeType实现了swagger类型与typescript的数据类型映射关系
最终通过转换生成模板字符串,经过prettier整理格式,使用bin目录下的node脚本输入出到output文件中中。
接口请求代码
背景
随着自我追求的不断变高(不是,其实是更懒了),就想到另外一个问题,既然我都能生成接口的请求类型和响应类型了,而且openapi规范中还规定了host、basePath、path等这些字段存在,已经能完整的具备了一个接口请求代码所需要的必要条件,那么我们能不能工程化的程度更彻底一点呢,直接通过openapi的规范直接生成接口请求的代码呢?答案是肯定的, 本着不重复造轮子的想法,迅速google,果然有人先动手了,@umijs/openapi, 乍一看是umijs的一个子项目有配套的umi插件, 其实这个库本身是跟框架解耦的,只要你是typescript的项目,后端接口遵循openapi规范就可以引入这个库。
