openapi-to-api

OpenAPI 转 API 工具

这个工具可以将 OpenAPI JSON 文件或在线 API 文档转换为前端调用的 API 代码。它会基于 OpenAPI 规范自动生成符合您项目结构的 API 调用函数。

安装

npm install openapi-to-api

使用方法

命令行使用

# 从本地 OpenAPI JSON 文件生成 API
npx openapi-to-api generate -f ./path/to/openapi.json -o ./api

# 从在线 API 文档生成 API
npx openapi-to-api generate -u https://example.com/api-docs.json -o ./api

# 使用自定义模板生成 API
npx openapi-to-api generate -f ./path/to/openapi.json -o ./api -t ./path/to/template.hbs

# 使用指定配置文件
npx openapi-to-api generate -c ./openapi-to-api.json

# 使用默认配置文件（无需指定路径）
npx openapi-to-api generate

# 创建配置文件模板
npx openapi-to-api init

命令参数

• -f, --file <file>: OpenAPI JSON 文件路径
• -u, --url <url>: OpenAPI JSON 文档在线地址
• -o, --output <o>: 生成的 API 文件输出目录，默认为 ./api
• -t, --template <template>: 自定义模板文件路径
• -c, --config <config>: 配置文件路径
• -r, --request-import-path <path>: request 模块的导入路径，默认为 @/utils/request.js

配置文件

您可以使用配置文件来集中管理工具的设置。创建配置文件：

npx openapi-to-api init

默认配置文件

工具支持自动查找并读取以下默认配置文件（按优先级排序）：

• .openapirc
• .openapirc.json
• .openapirc.js
• openapi-to-api.config.js
• openapi-to-api.config.json

如果您在项目根目录创建了上述任一文件，工具会自动读取该配置文件，无需通过 -c 选项指定。

配置文件示例

{
  "file": "./path/to/openapi.json",
  "output": "./api",
  "requestImportPath": "@/utils/request.js",
  "templateType": "default",
  "templateFile": "./custom-template.hbs",
  "fileMapping": {
    "用户管理": "user-service.js",
    "内容管理": "content-service.js"
  }
}

配置选项

• file: OpenAPI JSON 文件路径
• url: OpenAPI JSON 文档在线地址
• output: 生成的 API 文件输出目录
• requestImportPath: 请求模块的导入路径
• templateFile: 自定义模板文件路径
• templateType: 模板类型，可选值：default、fetch、custom
• fileMapping: 标签到文件名的映射，用于自定义生成的文件名

模板类型

工具支持多种模板类型，可以通过 templateType 配置：

• default: 默认模板，使用项目已有的请求模块，需要配置 requestImportPath。适合已经有自己请求库的项目。
• fetch: 使用原生 fetch API 的模板，不依赖任何外部库。适合不想引入额外依赖的项目。
• custom: 使用自定义模板，需要通过 templateFile 指定模板文件路径。

如果需要更高度自定义，可以通过 templateFile 指定自己的模板文件。

命令行参数会覆盖配置文件中的设置。

在代码中使用

const { generateApi } = require('openapi-to-api');

// 从本地文件生成 API
generateApi({
  file: './path/to/openapi.json',
  output: './src/api',
});

// 从在线 URL 生成 API
generateApi({
  url: 'https://example.com/api-docs.json',
  output: './src/api',
});

// 使用指定配置文件
generateApi({
  config: './openapi-to-api.json',
});

// 使用默认配置文件（不提供任何参数，自动查找）
generateApi();

// 使用 fetch 模板
generateApi({
  file: './path/to/openapi.json',
  output: './src/api',
  templateType: 'fetch',
});

自定义模板

默认模板生成的 API 文件格式类似于：

/**
 * XX相关接口
 * 由openapi-to-api自动生成
 */
import request from '@/utils/request.js';

/**
 * 分析英语作文
 * @param {Object} data - 请求数据
 * @returns {Promise}
 */
export function analyzeEssayAPI(data) {
  return request({
    url: '/api/ai/analyze-essay',
    method: 'post',
    data,
  });
}

您可以通过提供自定义模板文件来更改生成的 API 文件格式。模板使用 Handlebars 语法编写。

可用的模板变量：

• summary: API 分组的描述
• requestImportPath: 请求模块的导入路径
• operations: API 操作列表，每个操作包含：
  • summary: 操作描述
  • functionName: 函数名
  • url: API 路径
  • method: HTTP 方法 (get, post 等)
  • requestBody: 是否有请求体
  • hasParams: 是否有查询参数
  • parameters: 参数列表
  • paramName: 参数名称 (data 或 params)
  • paramDescription: 参数描述

路径参数处理

工具现在可以正确处理路径参数，例如：

/api/users/{id} -> /api/users/${id}
/api/articles/{articleId} -> /api/articles/${articleId}

默认模板会自动识别这些参数并生成正确的函数定义，带有参数和模板字符串 URL。

示例

假设有一个 OpenAPI JSON 文件包含以下端点：

/api/ai/analyze-essay
/api/users/{id}
/api/articles/{articleId}

运行命令：

npx openapi-to-api generate -f openapi.json -o ./api

将会在 ./api 目录下生成对应的 JavaScript 文件，包含这些端点的调用函数。

许可证

MIT