正文
手摸手教你用 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 配置工具
yarn add -D yapi-to-typescript
在项目根目录下创建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
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;
};