@wizmacau/openapi

簡介

@wizmacau/openapi 是一個功能強大的工具，用於從 OpenAPI Swagger JSON 生成 TypeScript 請求文件。它能夠自動解析 OpenAPI 文檔，並生成類型安全的 API 客戶端代碼，幫助開發者提高開發效率和代碼質量。

特點

• 類型安全：生成完整的 TypeScript 類型定義，提供編譯時類型檢查
• 自動化：從 OpenAPI 文檔自動生成 API 客戶端代碼
• 可定制：支持自定義模板和命名策略
• 易於集成：與現有項目無縫集成
• 支持最新標準：完全支持 OpenAPI 3.0 規範
• 優化的代碼輸出：生成符合項目風格的代碼，支持 Prettier 格式化
• 智能命名：服務文件使用 kebab-case 命名（如 file-template.ts），方法名使用 camelCase 命名且不帶前綴
• 靈活的模板：支持自定義模板，包括 React 環境下的請求模板

安裝

使用 npm 安裝：

npm install @wizmacau/openapi --save-dev

使用 yarn 安裝：

yarn add @wizmacau/openapi --dev

使用 pnpm 安裝：

pnpm add @wizmacau/openapi --save-dev

使用方法

基本用法

import { generateService } from '@wizmacau/openapi'

// 從本地文件生成
await generateService({
  schemaPath: './swagger.json',
  outputPath: './src/api',
  namespace: 'API',
  projectName: 'example',
})

// 從遠程 URL 生成
await generateService({
  schemaPath: 'https://example.com/swagger.json',
  outputPath: './src/api',
  namespace: 'API',
  projectName: 'example',
})

命令行使用

您也可以在 package.json 中添加腳本來使用：

{
  "scripts": {
    "generate-api": "node -e \"require('@wizmacau/openapi').generateService({ schemaPath: './swagger.json', outputPath: './src/api', namespace: 'API', projectName: 'example' })\""
  }
}

然後運行：

npm run generate-api

配置選項

| 選項 | 類型 | 必填 | 默認值 | 說明 | | ---------------------- | ------------------------------------------------------ | ---- | ------------------------------- | ---------------------------------------------- | | schemaPath | string | 是 | - | OpenAPI 文檔路徑，可以是本地文件路徑或遠程 URL | | outputPath | string | 否 | './src/services' | 生成代碼的輸出目錄 | | namespace | string | 否 | 'API' | 生成的類型和服務的命名空間 | | projectName | string | 否 | - | 項目名稱，用於生成子目錄 | | logLevel | 'debug' | 'info' | 'warn' | 'error' | 否 | 'info' | 日誌級別 | | namingStrategy | 'default' | 'camel' | 'pascal' | 'snake' | 'kebab' | 否 | 'default' | 命名策略 | | templateType | string | 否 | 'react' | 模板類型 | | templateDir | string | 否 | - | 自定義模板目錄 | | prettier | boolean | 否 | true | 是否使用 Prettier 格式化生成的代碼 | | strictNullChecks | boolean | 否 | true | 是否啟用嚴格的空值檢查 | | requestImportStatement | string | 否 | 'import { request } from "umi"' | 自定義 request 函數的導入語句 |

高級用法

自定義命名策略

您可以通過提供自定義的命名策略來控制生成的類型和服務的命名：

import { generateService } from '@wizmacau/openapi'

await generateService({
  schemaPath: './swagger.json',
  outputPath: './src/api',
  namespace: 'API',
  projectName: 'example',
  namingStrategy: 'pascal', // 使用 PascalCase 命名策略
})

自定義請求函數

您可以自定義 request 函數的導入語句：

import { generateService } from '@wizmacau/openapi'

await generateService({
  schemaPath: './swagger.json',
  outputPath: './src/api',
  namespace: 'API',
  projectName: 'example',
  requestImportStatement: 'import { request } from "@/utils/request"',
})

自定義模板目錄

您可以指定自定義的模板目錄：

import { generateService } from '@wizmacau/openapi'

await generateService({
  schemaPath: './swagger.json',
  outputPath: './src/api',
  namespace: 'API',
  projectName: 'example',
  templateDir: './my-templates', // 自定義模板目錄
  templateType: 'react', // 模板類型，對應模板目錄下的子目錄
})

模板目錄結構應該如下：

my-templates/
└── react/
    ├── index.ts.njk
    ├── service.ts.njk
    └── typings.d.ts.njk

生成的代碼結構

生成的代碼包含以下文件：

• index.ts - 導出所有服務和類型
• typings.d.ts - 包含所有類型定義
• {service-name}.ts - 每個服務的實現（使用 kebab-case 命名）

示例

生成的類型定義

// typings.d.ts
declare namespace API {
  type LoginParams = {
    username: string
    password: string
    remember?: boolean
  }

  type LoginResult = {
    status: 'ok' | 'error'
    type?: string
    currentAuthority?: string
  }
}

生成的服務實現

// auth.ts
import { request } from 'umi'

export async function login(params: API.LoginParams) {
  return request<API.LoginResult>('/api/login', {
    method: 'POST',
    data: params,
  })
}

貢獻

歡迎提交 Pull Request 和 Issue。

許可證

ISC