关于typescript:基于-Pipeline-的-TSJS-API-代码自动生成apipgen

大家写我的项目的时候联调对接后端，写相应的 API 函数的时候会不会感觉很麻烦，我是这么感觉的，如果应用的 Typescript，确保和后端的类型保持一致，还要手写类型，接口申请和返回参数定义类型成了繁琐的一件事件。

如果后端有提供接口形容的数据源（swagger、yapi 或其余源）等等，咱们就能够利用 aippgen 主动的生成接口与类型。

/**
 * @summary uploads an image
 * @method post
 */
export function postPetPetIdUploadImage(data: FormData, paths: OpenAPITypes.PostPetPetIdUploadImagePath, config?: AxiosRequestConfig) {const url = `/pet/${paths?.petId}/uploadImage`
  http.request<Response<OpenAPITypes.ApiResponse>>({url, data, ...config})
}
/**
 * @summary Add a new pet to the store
 * @method post
 */
export function postPet(data: OpenAPITypes.Pet, config?: AxiosRequestConfig) {
  const url = '/pet'
  http.request<Response<void>>({url, data, ...config})
}

export type Response<T> = T;

export interface ApiResponse {
  code?: number;
  type?: string;
  message?: string;
}
export interface Category {
  id?: number;
  name?: string;
}
export interface Pet {
  id?: number;
  category?: Category;
  name: string;
  photoUrls: string[];
  tags?: Tag[];
  /** @description pet status in the store */
  status?: string;
}

aippgen（API Pipeline Generator）是 API 生成工具，其中 Pipeline 是管道的意思，apipgen 通过不同的管道反对不同的源和输入格局，目前 apipgen 官网默认反对 swag-ts-axios、swag-js-axios 两种管道，反对自定义管道，不同管道间能够复用和重组。

要应用它之前，咱们先在本地我的项目文件夹中装置：

pnpm add apipgen -D
# Or Yarn
yarn add apipgen --dev

📖 应用

应用 apipgen 要先编写配置文件，由配置文件决定输出 / 输入的内容，反对多个格局的配置文件 .ts|.js|.cjs|.json

import {defineConfig} from 'apipgen'

export default defineConfig({
  /**
   * 应用的编译解决管道，反对 npm 包（增加前缀 apipgen-）或本地门路
   *
   * 默认反对 swag-ts-axios|swag-js-axios
   * @default 'swag-ts-axios'
   */
  pipeline: 'swag-ts-axios',
  // 输出源 (swagger url 或 swagger json) 以及输入源
  // 如果有多个源，能够应用 server 字段
  input: 'https://petstore.swagger.io/v2/swagger.json',
  output: {
    main: 'src/api/index.ts',
    type: 'src/api/index.type.ts',
  },

  // API baseUrl，此配置将传递给 axios
  baseURL: 'import.meta.env.VITE_APP_BASE_API',
  // 自定义 responseType，默认 T
  responseType: 'T extends {data?: infer V} ? V : void',
})

配置后，应用 apipgen 脚本生成代码：

# run apipgen
pnpm apipgen

提供源（input）

input 目前反对两个输出源 url|json

export default defineConfig({
  // 间接输出服务 url
  input: 'http://...api-docs',
  // 或者抉择其余源
  input: {/* url|json */}
})

多服务（Server）

如果有多个服务，能够应用 server 设置多个服务。顶层的其余配置会被用作附加配置

export default defineConfig({
  baseUrl: 'https://...',
  // 所有 server 都继承下层配置
  server: [{ uri: '...', import: '...', output: {/* ... */} },
    {uri: '...', import: '...', output: {/* ... */} },
    {uri: '...', import: '...', output: {/* ... */} },
  ]
})

导入（Import）

当然咱们我的项目中可能会想自定义 axios 拦截器，或应用 axios.create 的新实例，这个时候能够应用 import 字段自定义导入申请的门路。

不介意过渡封装 axios，这会毁坏 axios 本来的性能

咱们先在雷同目录下定义一个 http.instance.ts 用于配置 axios 申请

// 应用 axios.create 创立新的实例
const request = axios.create({baseURL: 'https://...'})
// 应用拦截器
request.interceptors.request.use(/* ... */)
request.interceptors.response.use(/* ... */)

接着咱们配置 apipgen.config 文件，增加 import 字段。

export default defineConfig({
  pipeline: 'swag-ts-axios',
  input: {uri: 'https://petstore.swagger.io/v2/swagger.json'},
  output: {main: 'src/apis/index.ts'},
  import: {
    // 将理论的 http 申请导入门路更改为 './http.instance'
    http: './http.instance'
  }
})

接着运行 apipgen，咱们就能失去具备拦截器的 axios 实例：

import http from "./http.instance";
import {AxiosRequestConfig} from "axios";
import * as OpenAPITypes from "./index.type";
import {Response} from "./index.type";

/**
 * @summary uploads an image
 * @method post
 */
export function postPetPetIdUploadImage(data: FormData, paths: OpenAPITypes.PostPetPetIdUploadImagePath, config?: AxiosRequestConfig) {const url = `/pet/${paths?.petId}/uploadImage`;
  http.request<Response<OpenAPITypes.ApiResponse>>({url, data, ...config});
}

Swagger 转 Javascript Axios

如果你的我的项目是 Javascript，应用 apipgen 的 swag-js-axios 管道还能够生成具备 TS 类型提醒的 JS 文件

export default defineConfig({
  pipeline: 'swag-js-axios',
  input: {uri: 'https://petstore.swagger.io/v2/swagger.json',},
})

export default defineConfig({
  pipeline: 'swag-js-axios',
  input: {uri: 'https://petstore.swagger.io/v2/swagger.json',},
})

/**
 * @summary uploads an image
 * @method post
 * @param {FormData} data
 * @param {import("./index.type").PostPetPetIdUploadImagePath} paths
 * @param {import("axios").AxiosRequestConfig=} config
 * @return {import("./index.type").Response<import("./index.type").ApiResponse>}
 */
export function postPetPetIdUploadImage(data, paths, config) {const url = `/pet/${paths?.petId}/uploadImage`
  http.request({url, data, ...config})
}

管道（Pipeline）

apipgen 由非凡的解决管道运作，从输出 config 到最终 dest 输入文件作为一个残缺管道。

apipgen 在定义配置时传入 pipeline 参数反对 npm 包（前缀 apipgen-）和本地门路。

咱们能够依据咱们不同的需要（源、调用的 http 申请库）自定义不同的解决管道：

export default defineConfig({pipeline: './custom-pipe',})

而管道中由 apipgen 提供的 pipeline 函数定义。

// custom-pipe.ts

// 应用 apipgen 提供的 pipeline 创立 API 管道生成器
import {pipeline} from 'apipgen'

// 每个管道都裸露了对应办法，能够进行复用并重组
import {dest, generate, original} from 'apipgen-swag-ts-axios'

function myCustomPipe(config) {
  const process = pipeline(
    // 读取配置，转换为外部配置，并提供默认值
    config => readConfig(config),
    // 获取数据源
    configRead => original(configRead),
    // 解析数据源为数据图表（graphs）configRead => parser(configRead),
    // 编译数据，转换为形象语法树（AST）configRead => compiler(configRead),
    // 生成代码（code）configRead => generate(configRead),
    // 利用 outputs 输入文件
    configRead => dest(configRead),
  )
  return process(config)
}

function readConfig(config) {// ...}

function parser(configRead) {// ...}

function compiler(configRead) {// ...}

如果大家感兴趣，会思考出一期怎么自定义 aippgen 管道的具体文章。

• Hairy’s Blog
• Github/TuiMao