umi配合Apifox实现openapi-generator和接口mock

背景

前端技术栈是umi+react+ts，后端接口更新频繁，前端侧还要再维护一遍数据结构，通过阅读接口文档每次手动更新interface的方式过于浪费时间，需要新建多个service，且只能配合接口管理工具去阅读后端的注释等等问题。接口管理工具用的是ApiFox,使用环境来做开发/测试环境区分，使用服务的概念来做不同模块的区分，区别就是不同服务的拼接前缀不同。

服务和环境的区别

使用场景示例：

环境：
  开发环境
  测试环境
  预发布环境
  正式环境

服务：
  用户服务（user.xxx.com）：登录等接口
  交易服务（trade.xxx.com）：交易相关接口
  直播服务（live.xxx.com）：直播相关接口

Umi的openapi-generator方案

umi有内置的openapi-generator方案，包为@umijs/max-plugin-openapi，如果是初始化的 ant pro 的模板项目，默认就有 openapi 功能，不用自己额外配置 plugins: ['@umijs/max-plugin-openapi']，否则需要在.umirc.ts文件中先引入插件。

注意：@umijs/plugin-openapi插件是旧版umi使用，新版已经不用这个包了。

再配置openApi的具体内容，openApi支持配置一个数组，方便多个服务配置。

也支持通过hook钩子自定义方法名和类名 。

bash 复制代码

   或本地地址： schemaPath: join(__dirname, 'oneapi.json'),

在 package.json 的 scripts 中增加一个命令。

json 复制代码

"openapi": "umi openapi",

配合ApiFox管理工具

注意：要通过ApiFox的生成代码工具，而不是导出，导出的内容和生成代码的内容不一致，配合@umijs/max-plugin-openapi会报错。

还需要把项目的唯一标识打开：

之后将openAPI格式URL配置到项目中即可。

问题

大坑：生成的项目中的package.json的文件一定要包含name！

因为使用ApiFox分了服务，拉下来的接口是不带服务前缀的，需要自己进行前缀拼接，apiPrefix: ''/hcsp-gateway/baseApi/v1''

PS：这里要写两个引号，否则自动拼接生成的会是一个变量而不是字符串。

这里还存在一个问题，ApiFox按照目录拉取接口报错，目前来看只能选择生成代码形式，和ApiFox技术人员沟通后，等待他们一个月内上线按照目录生成代码功能。现阶段不同的服务先全量拉取，通过修改apiPrefix拼接服务。

为什么不用umi的mock方案

使用ApiFox分了服务，也导致MOCK功能也只生成接口部分，并没有前缀，前缀需要自己拼接。这里有两种方案，1. 使用umi的本地MOCK方案，通过代理修改拼接前缀，但是由于mock文件都在一个目录下，如果是名称重复的接口，则不能拥有MOCK 2.使用Apifox的mock方案，优点是可视化，mock类型更精确，可以按照服务mock。

ApiFox的mock方案

apifox.com/help/api-mo...

TODO

umi的openapi-generator方案有很多缺陷，比如大部分open-api的API都不能用。且每次更新是全量更新，不能选择性更新，也不清楚每次都新增了什么，这里留个钩子，计划之后要自己基于openapi-generator库二次开发，加上以上功能：

增量提示
批量选择更新
友好的promat
按服务生成代码

openapi-generator

AntdPro的openapi-generator配置