前端开发必备！让接口调用更简单！@clean-js/api-gen新功能上线，支持运行时类型校验你是否也感到面对接口文档

引言

你是否也感到面对接口文档编写请求函数很繁琐？你是否也受到了来自同事的背刺，悄悄改了文档而没有通知你？你是否也遇到过明明定好了接口，而实际返回参数和接口不一致？

无论前端还是后端，或多或少都会遇到过这样的问题。不要担心，让 @clean-js/api-gen 帮你解决烦恼！

这个库支持 YAPI、Swagger 2、Swagger 3 等 API 文档生成请求代码，并且自动生成 TypeScript 输入和输出参数类型，简化了手动编写重复的请求代码和接口类型的烦恼，同时还会记录每一次文档变更，再也不怕同事背刺了（悄悄改文档）。

更重要的是，它还支持运行时类型校验！你可以启用 zod 校验功能，进行运行时类型检查，从而更加确保代码的质量和稳定性。

这样我们就可以在运行时对数据类型进行校验，在开发过程中及时发现错误，在线上环境中也可以通过sentry之类的平台上报错误，定位问题。

别再花费大量时间手写代码和类型定义了，快来使用 @clean-js/api-gen，让接口调用更简单！

安装

npm install @clean-js/api-gen

详细文档

功能

根据YAPI，swagger2，swagger3等api协议自动生成请求代码
声明完整的Typescript入参和出参类型
支持路径参数替换
YAPI会在注释中写入该接口的地址

方法命名规则为 method+url；如/user，method：post，生成的代码如下

    /** Yapi link: https://yapi.xxxx.com/project/2055/interface/api/125352 */
export function postUser(parameter: { body: PostUserBody }) {
  return Req.request<ResponsePostUser>({
    url: '/user',
    method: 'post',
    data: parameter.body,
  });
}

axios 生成代码如下

export function postDatasetVersionRecords(
  parameter: {
    body: any;
    path: {
      version: string;
      dataset: string;
    };
  },
  config?: AxiosRequestConfig,
) {
  return Req.request<ResponsePostDatasetVersionRecords>({
    url: replaceUrlPath('/{dataset}/{version}/records', parameter?.path),
    method: 'post',
    data: parameter.body,
    ...config,
  });
}

开启zod校验，则会生成zod类型，以及在接口返回之后进行校验

运行时类型校验

开启zod，可以用于接口返回数据的类型校验，发现线上问题在config文件中开启zod即可

export default {
  ...
  zod: true
}

配置错误处理函数

import { Req } from '@/clean-js/http.service';

Req.setZodErrorHandler((error, value, url, schema ) => {
    // 你可以在这里上报错误
    console.log(error)
});

自动生成的请求代码如下

   /** Yapi link: http://yapi.smart-xwork.cn/project/186904/interface/api/2625446 */
   export function getApiJymTest(config?: AxiosRequestConfig) {
     const s = z.object({
       field_1: z.string(),
       field_2: z.number(),
       field_3: z.array(z.object({ field_4: z.string(), field_5: z.number() })),
     });
     return Req.request<ResponseGetApiJymTest>({
       url: "/api/jym/test",
       method: "get",
       ...config,
     }).then((res) => {
       if (verifyZod && s) {
         verifyZod(s, res.data, "/api/jym/test");
       }
       return res;
     });
   }

当接口返回的数据校验错误的时候会打印错误信息，如下图，会打印具体的url和zod错误信息

接口文档变更记录功能

此外，还有一个文档变更记录功能
当文档发生变化，重新运行api-gen会生成diff记录,格式如下，记录新增，减少，变更多少api
这样每次文档变更都有迹可循，再也不怕同事悄悄改文档了

Date: 2022-11-26 12:26:34

Sum-up: Added 20 APIs Reduce 3 APIs

代码仓库

各位大佬，记得一键三连，给个star，谢谢

本文正在参加「金石计划」