手摸手教你用 yapi-to-typescript生成Yapi的TypeScript数据类型

一 背景

现代社会比较重视效率，本着这个思想宗旨，能用工具自动高效做的事情，就不要低质量的勤奋。yapi-to-typescript就是一款自动生成接口请求与响应的typescript数据类型定义的工具，可根据 YApi 或 Swagger 的接口定义生成 TypeScript 或 JavaScript 的接口类型及其请求函数代码。本文手把手教你在项目中把这个工具用起来，让加班时间少一点，摸鱼时间多一点。

二 安装配置

2.1 在项目中安装yapi-to-typescript工具包

yarn add -D yapi-to-typescript

2.2 配置工具

在项目根目录下创建yyt.config.ts配置文件

npx ytt init -c ytt.ts

每个配置项的含义参见官方配置文档，将初始配置文件修改为:

import { defineConfig } from 'yapi-to-typescript';

/**
 * 生成Api接口名称  Interface和ChangeCase数据类型参见node_modules\yapi-to-typescript\lib\esm\index.d.ts定义
 * @param interfaceInfo : Interface
 * @param changeCase:ChangeCase
 * @returns 请求响应接口名称--pascal命名
 */
function genApiInterfaceName(interfaceInfo, changeCase) {
  // 取解析路径dir最尾部的路径作为前缀路径
  const lastPath = interfaceInfo.parsedPath.dir.split('/').pop();
  // 拼接前缀路径+文件名称
  return `${changeCase.pascalCase(lastPath)}${changeCase.pascalCase(interfaceInfo.parsedPath.name)}`;
}

export default defineConfig([
  {
    serverUrl: 'http://yapi.xxx.com',
    typesOnly: true,
    target: 'typescript',
    reactHooks: {
      enabled: false,
    },
    prodEnvName: '项目名称',
    // 将生成文件路径转化成小驼峰命名方式
    outputFilePath: (interfaceInfo, changeCase) => {
      const filePathArr = interfaceInfo.path.split('/');
      const filePath = filePathArr.map((item) => changeCase.camelCase(item)).join('/');
      return `src/types/httpTypes/${filePath}.ts`;
    },
    // 生成ts文件中请求参数interface名称,将下划线命名转换成pascal命名
    getRequestDataTypeName: (interfaceInfo, changeCase) => {
      return `${genApiInterfaceName(interfaceInfo, changeCase)}Request`;
    },
    // 生成ts文件中请求响应数据interface名称,将下划线命名转换成pascal命名
    getResponseDataTypeName: (interfaceInfo, changeCase) => {
      return `${genApiInterfaceName(interfaceInfo, changeCase)}Response`;
    },
    // 响应数据中要生成ts数据类型的键名
    dataKey: 'retdata',
    projects: [
      {
        // token获取方式： 在yapi-设置-token配置中查看
        token: 'xxx-token',
        // 分类id查找方式: 点击接口左侧的分类菜单,查看url地址栏最后面的数字获取
        // 分类id配置特别重要,配置错了无法生成对应的ts数据类型定义文件
        categories: [
          {
            id: [139], // 批量加好友API分类id
          },
        ],
      },
    ],
  },
]);

其中token和projects--categories--id的查看方式分别是:

在package.json中添加指令

  "scripts": {
    "ytt": "ytt",
  },

三 生成使用

3.1 生成api接口请求与响应的ts数据类型

yarn yyt

注意：自动生成的ts数据类型文件,是不需要添加到git仓库中的,所以要在.gitignore中添加一条文件版本管理忽略规则

# 自动生成类型不允许上传
/src/types/httpTypes/*

3.2 引用方式

import type {AddClientToolsGetClientsRequest, AddClientToolsGetClientsResponse} from '@/types/httpTypes/addClientTools/getClients';

3.2 枚举类型配置方法

生成数据类型示例:

export type AddClientToolsGetClientsResponse = {
  ...,
  /**
   * 手机识别码
   */
  phoneCode: string
  /**
   * 添加好友状态标识 0-未添加 1-成功添加
   */
  state: 0 | 1
  /**
   * 复制次数
   */
  copyCount: number
}[]

四 踩坑分享

4.1 yyt.config.ts 中的projects--categories--id是个很关键的参数，如果配置错误，将无法生成ts数据类型定义文件。配置成[0]，是生成配置的token对应的api项目下所有接口的ts数据类型文档，配置成分组id,则生成的是配置的token对应的api项目下，某个分组的api接口请求与响应ts数据类型定义文件。

    projects: [
      {
        categories: [
          {
            id: [139], // 分组id,  如果配置成[0]是生成全部
          },
        ],
      },
    ],

4.2 自动生成api接口请求响应ts数据类型定义文档之后，在业务文件中引用时，却报引用路径有错误。解决方法: 以VSCode为例，按Ctrl+Shift+P，然后搜索重启TS服务器，重启TS服务，引用错误就会消失。

4.3  yyt工具对yapi的编写质量有一定的要求，如果后端编写接口太随意，会造成yyt指令执行报错。比如如下的错误，yapi上api的接口地址带有查询参数，而ts的数据类型文件路径是根据api的接口地址生成的,文件路径中是不允许出现?的，一般需要后端修改api地址，如果后端不能及时修改，前端没修改权限又着急用,可以改配置文件

    outputFilePath: (interfaceInfo) => {
      let filePathNames =  interfaceInfo.path；
      // ?在路径中是非法的,所以需要截取掉含有?的路径后面的字符 类似这种:getFundManagerAwards?personalCode=101000231.ts
      filePathNames = filePathNames.slice(0, filePathNames.lastIndexOf('?'));
      return `src/types/httpTypes/${filePathNames}.ts`;
    },

4.4 yapi get请求的参数，无法指定参数类型，自动生成的参数类型都是string，不能满足实际应用，需要对类型定义不符合使用场景的参数做如下处理：

import type {AddClientToolsGetClientsRequest, AddClientToolsGetClientsResponse} from '@/types/httpTypes/addClientTools/getClients';

type TTabVal = 1 | 2;

// 如果要对导出的类型个别字段类型进行修改,参照下方
type TReqParams = Omit<AddClientToolsGetClientsRequest, 'pageNum' | 'pageSize' | 'handleType'> & {
  pageNum: number;
  pageSize: number;
  handleType: TTabVal;
};