YApi to TypeScript

根据 YApi 的接口定义生成 TypeScript 的请求函数。

特性

自动登录，支持普通登录、LDAP 登录、openapi 登录
可导出同项目下的多个分类
可自定义接口名及请求函数名
完整的注释

安装

# yarn
yarn add yapi-to-typescript@0.10.4

# 或者，npm
npm i yapi-to-typescript@0.10.4

使用

yapi-to-typescript 安装完成后，我们就可以使用 ytt 命令进行相关操作。

生成配置文件

在使用前，我们应该在项目的根目录写入配置文件 ytt.config.ts，使用命令 ytt init 可快速创建配置文件，如果配置文件已存在，将会被覆盖：

# yarn
yarn ytt init

# 或者，npm
npm run ytt init

修改配置文件

打开 ytt.config.ts，按照说明修改相关配置项即可。查看配置说明

生成 TypeScript 定义文件

直接执行命令 ytt 即可抓取 YApi 的接口定义并生成相应的 TypeScript 定义文件：

# yarn
yarn ytt

# 或者，npm
npm run ytt

建议

因为 API 接口在开发过程中是不断变化的，建议你将 ytt 命令放入 package.json 的 scripts 字段中：

{
  "scripts": {
    "api": "ytt"
  }
}

然后更新 API 的 TypeScript 定义只需执行以下命令即可：

# yarn
yarn api

# 或者，npm
npm run api

配置项

projectUrl
- 类型: string
- 说明: 项目全部接口页面的 url。
- 举例: http://foo.bar/project/20/interface/api

login

类型:

{
  /** 登录方式：classical（普通登录）、ldap（LDAP） */
  method?: 'classical' | 'ldap',
  /** 登录邮箱 */
  email: string,
  /** 登录密码 */
  password: string,
} | {
  /** 登录方式：openapi（开放API，仅 YApi 版本大于等于 1.5.0 时可用） */
  method: 'openapi',
  /** 项目 token（进入项目的设置-->token配置获取） */
  token: string,
}

说明: 登录 YApi 的信息。（注意：使用 openapi 登录时 YApi 的版本应大于等于 1.5.0）

举例:

// 普通登录
{
  method: 'classical',
  email: 'hello@foo.bar',
  password: '123456'
}

// LDAP 登录
{
  method: 'ldap',
  email: 'hello@foo.bar',
  password: '123456'
}

// openapi 登录
{
  method: 'openapi',
  token: 'de4dae88c1458930e52ea402b91cc9a4493767938f054b59c7bb161aa0506246',
}

extraCookies
- 类型: string
- 说明: 随请求发送的其它 cookies。一般情况下可不予理会。
- 举例: a=1; b=2; isAdmin=true
targetFile
- 类型: string
- 说明: 生成的 TypeScript 文件路径，同时，如果同级目录下不存在 request.ts 文件，执行 ytt 时则会自动创建一个默认的 request.ts 文件。你应在 request.ts 文件里完成相关请求逻辑。
- 举例: src/api/index.ts
dataKey
- 类型: string
- 说明: 若接口返回的是类似 { code: number, msg: string, data: any } 这种数据，往往我们只需要 data，这时我们可设置 dataKey 为 data，则接口函数返回的就是 data 的值。
- 举例: data

categories

类型:

{
  /** 分类 id */
  [id: number]: {
    /** 获取发起请求函数的名称 */
    getRequestFunctionName: (api: ExtendedApi) => string,
    /** 获取 ts 接口的名称 */
    getInterfaceName: (api: ExtendedApi, interfaceType: InterfaceType) => string,
  },
}

说明: 要获取的分类列表，键为分类 ID，值为一个包含相关操作的对象。

举例:

{
  // 键是分类 ID，
  // 比如有接口分类的 url 为：http://foo.bar/project/20/interface/api/cat_55，
  // 则其 ID 为 55
  55: {
    // 下面的配置结果示例：
    // export function getUserInfo(data: GetUserInfoRequest): Promise<GetUserInfoResponse> { ... }
    // 获取接口名称，这里的接口指 TypeScript 中的 interface，非 api 接口
    getInterfaceName({ changeCase, parsedPath }, interfaceType) {
      const PascalName = changeCase.pascalCase(parsedPath.name)
      return `${PascalName}${interfaceType === InterfaceType.Request ? 'Request' : 'Response'}`
    },
    // 获取 api 接口函数名称
    getRequestFunctionName({ changeCase, parsedPath }) {
      return changeCase.camelCase(parsedPath.name)
    },
  },
}

常见问题

1. 如何上传文件？

场景描述： 在开发网页、微信小程序等应用时，常会遇到诸如设置头像之类的文件上传需求。但各端上传文件的方法是不一样的，对文件的描述也不一致。在接口处理时，如何兼容呢？

解决方案： 在调用接口请求函数时，对文件数据进行封装，在 request.ts 判断是否有文件数据，再进行相关处理。需注意的是，传给 request 函数的 fileData 已经解封，可以直接用。下面是一个在网页中上传用户头像的示例：

// app.ts
// 首先引入文件数据封装类
import { FileData } from 'yapi-to-typescript/lib/utils'
import { updateUserAvatar } from './api/index.ts'

// 调用更新用户头像接口请求函数
updateUserAvatar({
  image: new FileData(
    // 这里放原始文件数据，如 H5 中的 File、微信小程序中的文件路径
    document.querySelector('#avatar-input').files[0] 
  )
})

// api/request.ts
import { RequestPayload } from 'yapi-to-typescript/lib/types'

export default function request({
  path,
  method,
  requestBodyType,
  responseBodyType,
  data,
  fileData
}: RequestPayload): Promise<any> {
  return new Promise((resolve, reject) => {
    const hasFileData = Object.keys(fileData).length > 0
    if (hasFileData) {
      const fullData = {
        ...data,
        ...fileData
      }
      const formData = new FormData()
      Object.keys(fullData).forEach(key => {
        formData.append(key, fullData[key])
      })
      // http post 相关...
    }
  })
}

dive2Pro / yapi-to-typescript