@wizmacau/openapi v2.5.4

@wizmacau/openapi

此模組提供從 OpenAPI 架構生成服務介面的工具。它通過自動創建基於 OpenAPI 規範的 JavaScript 或 TypeScript 服務客戶端，簡化了 RESTful API 的整合過程。

安裝

npm install @wizmacau/openapi
yarn add @wizmacau/openapi
pnpm install @wizmacau/openapi

使用方法

CommonJS (CJS)

您可以在 Node.js 項目中按以下方式使用 @wizmacau/openapi 套件：

const openapi = require('@wizmacau/openapi');
const { generateService } = require('@wizmacau/openapi/dist/index');

// 從 OpenAPI 架構生成服務
generateService({
  schemaPath: 'https://yourdomain.com/swagger/v1/swagger.json',
  outputPath: `${__dirname}/output`,
  projectName: 'YourProject',
  namespace: 'YourNamespace'
}).then(() => {
  console.log('服務生成完成！');
});

在項目中使用

步驟 1: 創建配置文件

在項目根目錄創建 openapi.config.mjs (ESM) 或 openapi.config.cjs (CommonJS) 文件。以下是兩種格式的示例：

ESM 格式 (openapi.config.mjs)

import { defaultNormalizeMethodNameV3 } from '@wizmacau/openapi/dist/hooks';

export default {
  // OpenAPI/Swagger 文檔的 URL 或本地文件路徑
  schemaPath: 'https://api.example.com/v1/swagger.json',
  // 生成的代碼輸出目錄
  outputPath: './src/services',
  // 項目名稱，會用於生成註釋
  projectName: 'MyProject',
  // API 命名空間
  namespace: 'API',
  // 自定義 hooks
  hooks: {
    normalizeMethodName: defaultNormalizeMethodNameV3,
  },
  // 是否生成 mock 數據
  mockData: false,
  // 請求庫，支持 axios, fetch, request
  requestLibrary: 'axios',
  // 生成的文件類型，支持 ts, js
  language: 'ts',
};

CommonJS 格式 (openapi.config.cjs)

const { defaultNormalizeMethodNameV3 } = require('@wizmacau/openapi/dist/hooks');

module.exports = {
  schemaPath: 'https://api.example.com/v1/swagger.json',
  outputPath: './src/services',
  projectName: 'MyProject',
  namespace: 'API',
  hooks: {
    normalizeMethodName: defaultNormalizeMethodNameV3,
  },
  mockData: false,
  requestLibrary: 'axios',
  language: 'ts',
};

步驟 2: 配置 package.json

在您的項目 package.json 中添加以下 scripts：

{
  "scripts": {
    "openapi": "zeus-openapi",
    "openapi:watch": "zeus-openapi --watch"
  }
}

步驟 3: 生成 API 代碼

運行以下命令生成 API 代碼：

# 一次性生成
pnpm run openapi

# 監聽模式，當 OpenAPI 文檔更新時自動重新生成
pnpm run openapi:watch

步驟 4: 使用生成的 API

生成的 API 代碼位於 outputPath 指定的目錄中，您可以直接導入並使用：

import { someApi } from './services';

// 使用生成的 API
const response = await someApi.getUserInfo({ userId: 1 });

配置文件格式選擇

CommonJS (*.cjs) 使用場景

• 在較舊的 Node.js 項目中
• 當項目的 package.json 中沒有設置 "type": "module"
• 當項目中主要使用 require() 進行模塊導入
• 需要與其他 CommonJS 模塊互操作的場景

ESM (*.mjs) 使用場景

• 在現代 Node.js 項目中
• 當項目的 package.json 中設置了 "type": "module"
• 當項目中主要使用 import/export 語法
• 需要使用 ES 模塊特性（如頂層 await）的場景

配置選項說明

以下是支持的配置選項：

hooks 配置項

{
  hooks?: {
    // 用於自定義類型名稱的生成規則
    normalizeTypeName?: (modelName: string) => string;
    // 用於自定義服務名稱的生成規則
    normalizeServiceName?: (tag: string) => string;
    // 用於自定義方法名稱的生成規則
    normalizeMethodName?: (operation: OperationObject) => string;
  }
}

配置文件示例

import { defaultNormalizeMethodNameV3 } from '@wizmacau/openapi/dist/hooks';

export default {
  schemaPath: 'https://api.example.com/v1/swagger.json',
  outputPath: './src/services',
  projectName: 'MyProject',
  namespace: 'API',
  logLevel: 'info',
  hooks: {
    normalizeMethodName: defaultNormalizeMethodNameV3,
  },
  isReactNative: false,
  requestImportStatement: `import { request } from './request';`,
};

Hooks 配置說明

在生成服務時，您可以通過配置不同的 hooks 來自定義代碼生成的行為。主要包括以下幾種 hooks：

normalizeMethodName

用於自定義 API 方法名稱的生成規則。提供了三個預設版本：

1. defaultNormalizeMethodNameV1（舊版本兼容）

   • 處理邏輯：從 operationId 中移除第一段（服務名），並將最後一段移到最前面
   • 適用場景：舊版本 API 格式兼容

2. defaultNormalizeMethodNameV2（預設）

   • 處理邏輯：移除第二段（模塊名），因為通常與服務名重複
   • 適用場景：標準 API 命名格式

3. defaultNormalizeMethodNameV3（新版本）

   • 處理邏輯：
     • 自動移除 HTTP 方法前綴（GET、POST 等）
     • 處理 JavaScript 關鍵字衝突
     • 提供更智能的命名轉換
   • 適用場景：現代 API 命名規範

使用示例：

const { generateService } = require('@wizmacau/openapi');
const { defaultNormalizeMethodNameV3 } = require('@wizmacau/openapi/dist/hooks');

generateService({
  // ... 其他配置
  hooks: {
    normalizeMethodName: defaultNormalizeMethodNameV3,
  },
});

normalizeServiceName

用於自定義服務名稱的生成規則。預設使用 defaultNormalizeServiceName，將標籤名轉換為駝峰命名。

normalizeTypeName

用於自定義類型名稱的生成規則。目前提供兩個版本：

1. defaultNormalizeTypeName（舊版本）

   • 支持泛型類型處理
   • 自動處理 Response 類型
   • 移除冗餘的命名部分（如 Models、Dtos）

2. zeusV3NormalizeTypeName（預設，推薦）

   • 保持後端定義的類型名稱不變
   • 適用於後端已經規範化類型命名的情況
   • 避免不必要的命名轉換

使用示例：

import { generateService } from '@wizmacau/openapi';

// zeusV3NormalizeTypeName 已經是默認的類型名稱生成器
generateService({
  // ... 其他配置
});

// 示例：
// 後端定義的類型名稱會被完整保留
// UserResponse -> UserResponse
// OrderRequest -> OrderRequest
// ProductPagedResponse -> ProductPagedResponse