@vue3-oop/ts-gear v4.12.0

ts-gear

English doc

用途

自动从swagger生成ts类型与请求接口的函数

方便的感知后端接口定义的变化。

起源

inspired by pont

ts-gear命名：ts是typescript与swagger的组合，gear寓意通过这个工具像齿轮一样，将前后端紧密的结合在一起，构成一架严密运转的机器。

后来想想，其实应该是与openapi结合而不仅限与swagger，不过名字起了挺久那就这样吧不改了。

用法

安装

yarn add ts-gear -D
// or
npm install ts-gear -D

生成初始化配置

在项目src目录下生成配置文件tsg.config.ts。

tsg -i

💡 因为该配置文件与请求函数有关，会在生成的代码调用，因此放到src文件夹中。

运行tsg

npx tsg // default use `src/tsg.config.ts`
// or assign another config file
npx tsg -c other_dir/tsg.config.ts
// or if only need update one project, use -p for the project name
npx tsg -p pet

查看src/service文件夹，结构如下

▾ src/
  tsg.config.ts
  ▾ service/
    ▾ pet/
        definition.ts
        request.ts
        index.ts

more directory information

如何在代码中调用

例如：在src/store/pet.ts文件中

import { getPetPetId } from '../../service/pet'

getPetPetId({
  path: {
    petId: 1
  }
}).then(pet => {
  console.log(pet)
  // pet will be the instance of Pet, it has Pet properties.
})

V4不兼容更新

• 默认请求函数的参数与返回值类型不在导出，推荐使用类型工具Parameters与ReturnType来从请求函数类型本身获取。

  如果需要导出参数与返回值类型，可配置项目中的

  shouldExportRequestOptionType: true
  shouldExportResponseType: true

• 默认不生成mock数据，需要的话可配置shouldGenerateMock: true，生成独立的mockRequest文件。

新配置项

• generateRequestFunctionName

例如：

generateRequestFunctionName: ({
  httpMethod: 'get' | 'put' | 'post' | 'delete' | 'options' | 'head' | 'patch'
  pathname: string
  schema: Path // openapi类型定义中的Path，内容太多不详细说了
}): string => {
  return `${httpMethod}${upperFirst(pathname.repalce('/api/commonPath', ''))}`
}

• shouldGenerateMock，是否生成mock数据，默认为false，不生成。

• generateRequestFunction，生成请求函数体，用这个的话，函数内容ts-gear就不再管了，完全由这个自定义函数生成，慎重使用🙏。

测试覆盖约50%，大概🤪，覆盖率统计比实际测试的显示的多

Statements

Branches

Functions

Lines

运行步骤

• 读取配置文件。

• 读取命令行参数过滤需要解析的项目。

• 获取各个项目的openapi数据。

• 如果设置了翻译，调用翻印接口。

• 统一格式化所有特殊字符。

• 解析范型名称。

• 将所有请求与定义名称组装到内部的全局变量中。

• 配置当前输出换行符。

• 准备好输出文件夹。

• 写入枚举与基础类型定义。

• 写入请求函数。

• 生成一个导出所有内容的索引文件index.ts。

其他类似工具

• OpenAPI Generator

• swagger-codegen

• oazapfts

本项目的特色

大多数其他类型的openapi生成工具对原始定义的要求较高，容错率低，而且没有做生成范型的处理。而这几项目都是本工具的重点解决亮点。

支持 OpenAPI Specification v2 v3.

配置样例

tsg.config.ts example

import type { Project } from 'ts-gear'

const projects: Project[] = [
  { ... }
]

export default projects

配置项说明

注意：以下所有配置的相对路径，都是tsg.config.ts文件所在的路径。例如该文件位置为src/tsg.config.ts，则配置中的路径都是相对src路径而定

axios

ts-gear内置的axiosRequester接受一个axios的实例作为参数，如果没有则使用默认的axios。

对于axios的各种配置可自己首先创建一个axios实例，然后传入axiosRequester使用。

目录结构

• definition.ts由definitions部分生成，包含所有基础类型定义。

• request.ts由paths生成，请求函数的命名规则：http request + api path，例如:

  "paths": {
    "/pet": {
      "post": { // 生成 `postPet`
      ...
      },
    },
    "/pet/findByTags": {
      "get": { // 生成 'getPetFindByTags'
      ...
      },
    },
    "/pet/{petId}": {
      "get": { // 生成 'getPetPetId' function
      ...
      },
    },

• index.ts是definition.ts与request.ts的导出出口文件。

每个请求函数的入参与返回数据类型，都会生成确定的ts类型。

如果生成的请求函数不能满足需求，也可以只使用definition.ts中的数据类型定义。

Hooks

为代码生成的生命周期中提供一些中间可以插入的步骤。

• beforeWriteTs: (o: { project: Project } & PrepareToWrite) => Promise

• afterWriteTs: (o: { project: Project } & PrepareToWrite) => Promise