openapi-v3-request-generator

• openapi-v3-request-generator 是一款基于openAPI v3的自动请求文件生成插件。
• 使用简单 且能实现高度自定义配置
• onGenRequestFnHook 实现自定义请求方法生成 勾子函数

安装

npm install openapi-v3-request-generator --dev

或者

yarn add openapi-v3-request-generator --dev

一、基本使用

在 package.json 文件script中新增 "gen": "openv3gen" 命令

// package.json
{
  "script": {
    "gen": "openv3gen",
  }
}

1.1 openapi.config.json5 配置说明

当项目根目录没有配置文件时 运行 yarn gen 或者 npm gen 脚本会自动在项目根目录中创建配置文件，无需手动创建

/**本文件为JSON5格式 安装json5 syntax vscode插件即可高亮展示 */
{
  /** 生成模式 true:生成ts文件 false:生成js文件 默认值为true */
  "tsMode": true,
  /** 生成物存储目标文件夹 */
  "targetDir": "./api",
  /** axios 实例文件地址 可选,默认值 "@/plugins/axios" 即 import http from '@/plugins/axios' */
  "requestLibPath": "@/plugins/axios",
  /** api-docs 可多个文档地址 */
  "projects": [
    {
      /** axios 实例文件地址 优先级高于父级配置 可选 */
      "requestLibPath": "@/plugins/axios",
      /** api-docs 文档地址 */
      "url": "https:/api.yourserver.com/api/v3/api-docs",
      /** 项目文件夹二级目录 /api/beam-server2 */
      "projectName": "beam-server",
      /** API请求地址前缀 可选 默认值为空*/
      "apiRequestUrlPrefix": "/beam-server"
    },
  ]
}

1.2 独立请求类型及响应类型声明使用示例

import { login } from '@/server-api/user'
import type { TloginBodyRequest, TloginPathRequest, TloginQueryRequest, TloginResponse } from '@/server-api/user.types'

const model: {
  data: TloginBodyRequest
  paths: TloginPathRequest
  query: TloginQueryRequest
} = {
  data: [],
  path: [],
  query: [],
}

const result: TloginResponse = {
  data: []
}
TemplateFileCopy(model).then((res) => {
	result.data = res
})

二、进阶使用

2.1 自定义生成请求钩子函数使用

import ApiBuilder from 'openapi-v3-request-generator'

new ApiBuilder({
  url: 'https://api.xxx.com/api/v3/api-docs',
  projectName: 'beam-server',
  targetDir: './src/server',
  onGenRequestFnHook: (config) => {
    let reqParams = 'params: {'
    if (config.paramsList.body.num) {
      reqParams += `
        data${config.paramsList.body.required ? '' : '?'}: ${config.paramsList.body.type}
      `
    }
    if (config.paramsList.path.num) {
      reqParams += `
        paths${config.paramsList.path.required ? '' : '?'}: ${config.paramsList.path.type}
      `
    }
    if (config.paramsList.query.num) {
      reqParams += `
        query${config.paramsList.query.required ? '' : '?'}: ${config.paramsList.query.type}
      `
    }
    if (config.paramsList.body.num || config.paramsList.path.num || config.paramsList.query.num) {
      reqParams += '}'
    } else {
      reqParams = ''
    }

    let pathVarables = ''
    let requestPath = ''
    if (config.paramsList.path.num > 0) {
      requestPath = config.path.replace(/\{/g, '${')

      // 匹配出地址栏的参数 例：/gitlab/projects/{gitlabProjectId}/files/{ref}/
      const regex = /{(.*?)}/g;
      const matches = config.path.match(regex)?.map(function(match) {
        return match.replace(/[{}]/g, '')
      })
      if (matches?.length) {
        pathVarables = `const { ${matches.join(',')} } = params?.paths || {}`
      }
    }

    return `
      /** ${config.summary || '后端没有提供注释'} */
      export const ${config.operationId} = (${reqParams}) => {
        ${pathVarables}
        return ${config.requestLibFnName}({
          url: '${config.path}',
          method: '${config.method}',
          ${config.paramsList.body.num ? 'data: params.data,' : ''}
          ${config.paramsList.query.num ? 'params: params.query,' : ''}
        })
      }
    `
  }
})

2.2 自定义生成请求文件名称钩子函数使用 onGenRequestFileNameHook

import ApiBuilder from 'openapi-v3-request-generator'
new ApiBuilder({
  url: 'https://api.xxx.com/api/v3/api-docs',
  projectName: 'beam-server',
  targetDir: './src/server',
  onGenRequestFileNameHook: (tag) => {
  	 return tag + 1234
  }
})

三、更新日志

• 修复正则判断文件名是否包含特色字符提示错误
• 新增TS模式下生成的请求参数与返回参数 独立的类型声明文件
• 调整单个请求参数类型 不再使用对象传递参数
• 调整js模式下单个请求参数类型 不再使用对象传递参数
• 新增 操作模块名称中文转拼音功能

v2.0.3

• 新增文件对比功能，自动对比文件差异，并生成差异文件
• /* @ts-ignore */ 头注释，避免ts报错影响打包

v2.0.4

• 根据 export 字符 判断是否有导出 无则不生成类型声明文件

v2.0.6

• 调整生成文件名称为kebab-case，防止操作系统文件名称大小写不敏感问题

v2.0.7

• 新增 include 配置项，用于指定只生成指定路径的接口
• 新增 exclude 配置项，用于指定排除指定路径的接口

v2.0.8

• 新增 多项目检测功能、如果有多个交互式命令行可选择要生成请求文件的服务
• 去除 去除生成请求函数中的时间头文件注释

v3.0.4

• 新增请求函数名称生成模式

/**本文件为JSON5格式 安装json5 syntax vscode插件即可高亮展示 */
{
  /** 生成模式 true:生成ts文件 false:生成js文件 可选配置 默认值为true */
  "tsMode": true,
  /** 生成物存储目标文件夹 */
  "targetDir": "./api",
  "requestFunctionNameMode": "path", // path / operationId 默认值 operationId
}