moyan-api 1.0.80 → 1.0.82

package/CHANGELOG.md

@@ -2,6 +2,10 @@
 
 All notable changes to this project will be documented in this file. See [standard-version](https://github.com/conventional-changelog/standard-version) for commit guidelines.
 
+### [1.0.82](https://gitee.com/ymoo/moyan-api/compare/v1.0.81...v1.0.82) (2026-03-24)
+
+### [1.0.81](https://gitee.com/ymoo/moyan-api/compare/v1.0.80...v1.0.81) (2026-03-24)
+
 ### [1.0.80](https://gitee.com/ymoo/moyan-api/compare/v1.0.79...v1.0.80) (2026-03-20)
 
 ### [1.0.78](https://gitee.com/ymoo/moyan-api/compare/v1.0.79...v1.0.78) (2026-03-20)

package/README.md

@@ -1,165 +1,333 @@
-# moyan-api 使用
-
-### 描述
-    用于生成OAS3 的调用api
-
-### 安装
-```sh
-npm i moyan-api -S 
-```
-
-### pageage配置
-```json
-#pageage.json
-{
-  "moyan-api":{
-    "output":"src", // 生成的文件输出目录，默认值：src
-    "apijson":"moyan.api.json" ,// 生成sdk 的openApi 3.0 数据 ，默认值：moyan.api.json
-    "jsonurl":"远程获取数据的地址", 
-    "apiprefix":"Api",
-  }
-}
-```
-
-### 使用
-* 调用命令前，必须保证你的项目根目录里面存在moyan.api.json（openApi 3.0格式的数据）或者在ageage.json中配置
-```json
-{
-   "moyan-api":{
-       "jsonurl":"远程获取数据的地址"
-   } 
-}
-```
-```sh
-cd 你的项目根目录
-moyan-api 
-```
-调用命令后会在我们的src/api 生成index.ts、schemas.ts两个文件，其中index.ts中的class就是我们的api调用类了。
-
-### 调用
-* 在我们开始调用api之前，我们需要对我们的 ApiCall 类做一些配置处理。
-* 我们可以在我们的src/lib/api下创建一个config.ts （具体文件名、路径可根据自己的喜好创建修改）。
-```TypeScript
-
-import { ElMessage } from 'element-plus'
-import { getConfig } from '../../config'
-import axios, { AxiosInstance, AxiosRequestConfig } from 'axios'
-import { ApiCall, ApiEntity } from 'moyan-api'
-const AXIOS = Symbol('mo#Api#axios')
-
-export class MoAxios {
-  static [AXIOS]: AxiosInstance
-  options: any = {}
-
-  constructor(options: any = {}) {
-    this.options = options
-  }
-
-  get $axios() {
-    if (!MoAxios[AXIOS]) {
-      MoAxios[AXIOS] = axios.create(this.config.axios)
-      this.init()
-    }
-    return MoAxios[AXIOS]
-  }
-
-  get config() {
-    return getConfig()
-  }
-
-  init() {
-    this.$axios.interceptors.response.use(
-      (res) => {
-        if (typeof this.options.render === 'function') {
-          return this.options.render(res)
-        } else {
-          return res
-        }
-      },
-      async (error) => {
-        // Do something with response error
-        if (error && error.response) {
-          switch (error.response.status) {
-            case 502:
-              error.message = '网关错误'
-              break
-            case 504:
-              error.message = '网关超时'
-              break
-            case 505:
-              error.message = '版本不受支持'
-              break
-            default:
-              error.message = error.response.data.message
-              break
-          }
-        }
-        throw error
-      }
-    )
-  }
-
-  request(apiEntity: ApiEntity) {
-    const url = `${apiEntity.path}`
-    const requsetOption: AxiosRequestConfig = {
-      responseType: 'json',
-      baseURL: this.config.moApi.baseURL,
-      url,
-      method: apiEntity.method,
-      headers: {}
-    }
-
-    if (apiEntity.method === 'GET') {
-      requsetOption.params = { params: apiEntity.params }
-    } else {
-      requsetOption.data = apiEntity.params
-    }
-    return this.$axios(requsetOption)
-  }
-}
-
-ApiCall.hintSuccessHandler = (apiCall) => {
-  console.info('请求成功！！')
-  ApiCall.hasPrompted = true
-  ElMessage.success({
-    message: apiCall.successMsg,
-    onClose: () => {
-      ApiCall.hasPrompted = false
-    }
-  })
-}
-
-ApiCall.hintFailHandler = (apiCall) => {
-  console.info('请求错误！！')
-  ApiCall.hasPrompted = true
-  apiCall.failMsg &&
-    ElMessage.error({
-      message: apiCall.failMsg,
-      onClose: () => {
-        ApiCall.hasPrompted = false
-      }
-    })
-}
-
-ApiCall.use(new MoAxios())
-
-```
-* 现在我们就可以在我们的项目中调用api了
-```TypeScript
-new ApiGetUser({params:{id:1}}).then((res)=>{
-    ...
-})
-
-
-new ApiGetUser({query:{id:1}}).then((res)=>{
-    ...
-})
-
-new ApiUpdateUser({query:{id:1},params:{name:'张三'}}).then((res)=>{
-    ...
-})
-
-```
-
-### Gitee
-https://gitee.com/ymoo/moyan-api
+# moyan-api
+
+基于 OpenAPI 3.0 (OAS3) 规范自动生成 TypeScript API 调用 SDK 的工具。
+
+## 功能特点
+
+- 根据 OpenAPI 3.0 JSON 自动生成 TypeScript 类型安全的 API 调用类
+- 支持本地文件和远程 URL 获取 API 定义
+- 自动生成接口类型定义和 Schema 类型
+- 支持自定义 API 类名前缀和请求路径前缀
+- 内置请求拦截器和响应处理器
+- 支持事件监听和自定义错误处理
+
+## 安装
+
+```sh
+npm i moyan-api -S
+```
+
+## 快速开始
+
+### 1. 项目配置
+
+在项目的 `package.json` 中添加配置：
+
+```json
+{
+  "moyan-api": {
+    "output": "src",              // 生成文件的输出目录，默认：src
+    "apijson": "moyan.api.json",  // OpenAPI 3.0 本地 JSON 文件路径，默认：moyan.api.json
+    "jsonurl": "https://...",     // 远程 OpenAPI JSON 地址（二选一）
+    "apiprefix": "Api",           // 生成的 SDK 类名前缀，默认：Api
+    "pathprefix": "/api",         // 请求路径前缀，默认：空
+    "dirname": "api"              // 生成的 SDK 目录名，默认：api
+  }
+}
+```
+
+### 2. 准备 OpenAPI 数据
+
+确保项目根目录存在 OpenAPI 3.0 格式的 JSON 文件（如 `moyan.api.json`），或在 `package.json` 中配置 `jsonurl` 从远程获取。
+
+### 3. 生成 SDK
+
+在项目根目录运行命令：
+
+```sh
+npx moyan-api
+```
+
+或使用 CLI 参数：
+
+```sh
+npx moyan-api -a moyan.api.json -o src -af Api -pp /api
+```
+
+命令执行后，会在指定目录（默认 `src/api`）生成以下文件：
+
+| 文件 | 说明 |
+|------|------|
+| `index.ts` | API 调用类定义 |
+| `schemas.ts` | 数据类型定义 |
+
+### 4. 配置请求类
+
+在使用 API 之前，需要配置 `ApiCall` 的请求实现。建议在 `src/lib/api/config.ts`（路径可自定义）中创建配置：
+
+```typescript
+import { ElMessage } from 'element-plus'
+import { getConfig } from '../../config'
+import axios, { AxiosInstance, AxiosRequestConfig } from 'axios'
+import { ApiCall, ApiEntity } from 'moyan-api'
+
+const AXIOS = Symbol('mo#Api#axios')
+
+export class MoAxios {
+  static [AXIOS]: AxiosInstance
+  options: any = {}
+
+  constructor(options: any = {}) {
+    this.options = options
+  }
+
+  get $axios() {
+    if (!MoAxios[AXIOS]) {
+      MoAxios[AXIOS] = axios.create(this.config.axios)
+      this.init()
+    }
+    return MoAxios[AXIOS]
+  }
+
+  get config() {
+    return getConfig()
+  }
+
+  init() {
+    this.$axios.interceptors.response.use(
+      (res) => {
+        if (typeof this.options.render === 'function') {
+          return this.options.render(res)
+        }
+        return res
+      },
+      async (error) => {
+        if (error && error.response) {
+          switch (error.response.status) {
+            case 502:
+              error.message = '网关错误'
+              break
+            case 504:
+              error.message = '网关超时'
+              break
+            case 505:
+              error.message = '版本不受支持'
+              break
+            default:
+              error.message = error.response.data.message
+              break
+          }
+        }
+        throw error
+      }
+    )
+  }
+
+  request(apiEntity: ApiEntity) {
+    const url = `${apiEntity.path}`
+    const requestOptions: AxiosRequestConfig = {
+      responseType: 'json',
+      baseURL: this.config.moApi.baseURL,
+      url,
+      method: apiEntity.method,
+      headers: {}
+    }
+
+    if (apiEntity.method === 'GET') {
+      requestOptions.params = apiEntity.params
+    } else {
+      requestOptions.data = apiEntity.params
+    }
+    return this.$axios(requestOptions)
+  }
+}
+
+// 成功提示处理器
+ApiCall.hintSuccessHandler = (apiCall) => {
+  ApiCall.hasPrompted = true
+  ElMessage.success({
+    message: apiCall.successMsg,
+    onClose: () => {
+      ApiCall.hasPrompted = false
+    }
+  })
+}
+
+// 失败提示处理器
+ApiCall.hintFailHandler = (apiCall) => {
+  ApiCall.hasPrompted = true
+  apiCall.failMsg &&
+    ElMessage.error({
+      message: apiCall.failMsg,
+      onClose: () => {
+        ApiCall.hasPrompted = false
+      }
+    })
+}
+
+// 注册请求实现
+ApiCall.use(new MoAxios())
+```
+
+### 5. 调用 API
+
+配置完成后，即可在项目中调用生成的 API：
+
+```typescript
+// GET 请求 - 使用 params
+new ApiGetUser({ params: { id: 1 } }).then((res) => {
+  // 处理响应
+})
+
+// GET 请求 - 使用 query（路径参数）
+new ApiGetUser({ query: { id: 1 } }).then((res) => {
+  // 处理响应
+})
+
+// PUT 请求 - 带路径参数和请求体
+new ApiUpdateUser({
+  query: { id: 1 },
+  params: { name: '张三' }
+}).then((res) => {
+  // 处理响应
+})
+```
+
+## CLI 参数
+
+| 参数 | 简写 | 说明 |
+|------|------|------|
+| `--apijson` | `-a` | OpenAPI JSON 文件路径 |
+| `--output` | `-o` | 输出目录路径 |
+| `--dirname` | `-d` | 生成的 SDK 目录名 |
+| `--jsonurl` | `-j` | 远程 OpenAPI 数据地址 |
+| `--apiprefix` | `-af` | 生成的 SDK 类名前缀 |
+| `--pathprefix` | `-pp` | 请求路径前缀 |
+
+## 编程方式使用（多配置批量生成）
+
+如果需要同时生成多个模块的 API SDK，可以创建配置文件使用编程方式调用：
+
+```javascript
+// generate-api.js
+const { ApisdkCreator } = require('moyan-api/dist/main.js')
+const { Program } = require('moyan-api/dist/program.js')
+
+const configs = [
+  {
+    jsonurl: 'http://localhost:8080/apiDoc/main-app',
+    output: './src/apis',
+    dirname: 'main-app'
+  },
+  {
+    jsonurl: 'http://localhost:8080/apiDoc/micro-system',
+    output: './src/apis',
+    dirname: 'micro-system'
+  },
+]
+
+const create = async () => {
+  for (let i = 0; i < configs.length; i++) {
+    await new ApisdkCreator(new Program(configs[i])).create()
+  }
+}
+
+create()
+```
+
+在 `package.json` 中添加脚本：
+
+```json
+{
+  "scripts": {
+    "generate-api": "node generate-api.js"
+  }
+}
+```
+
+然后运行：
+
+```sh
+npm run generate-api
+```
+
+### Program 配置项
+
+| 属性 | 说明 |
+|------|------|
+| `jsonurl` | 远程 OpenAPI JSON 地址 |
+| `apijson` | 本地 OpenAPI JSON 文件路径 |
+| `output` | 输出目录路径 |
+| `dirname` | 生成的 SDK 目录名 |
+| `apiprefix` | 生成的 SDK 类名前缀 |
+| `pathprefix` | 请求路径前缀 |
+
+## 导出的类型和接口
+
+```typescript
+import {
+  ApiCall,        // API 调用基类
+  ApiEntity,      // API 实体接口
+  ApiCallProps,   // API 调用参数类型
+  SubApiEntity,   // 子 API 实体接口
+  ObjectAny,      // 任意对象类型
+  Option,         // 请求选项类型
+  MoMethod        // HTTP 方法类型
+} from 'moyan-api'
+```
+
+## 请求选项 (Option)
+
+```typescript
+interface Option {
+  fileName?: string      // 下载文件的文件名
+  prefix?: boolean       // 是否使用 API 的 prefix，默认 true
+  hintSuccess?: boolean  // 是否显示成功提示，默认 true
+  hintFail?: boolean     // 是否显示失败提示，默认 true
+  showLoading?: boolean  // 是否显示加载蒙版，默认 false
+  loading?: boolean      // 加载状态
+  successMsg?: string | ((res: any) => string)  // 成功提示消息
+  failMsg?: string | ((err: any) => string)     // 失败提示消息
+  ext?: Record<string, any>  // 扩展字段
+}
+```
+
+## 事件监听
+
+`ApiCall` 内置了事件系统，可用于监听请求状态：
+
+```typescript
+import { ApiEvents } from 'moyan-api'
+
+// 监听请求成功
+ApiCall.emitter.on(ApiEvents.HintSuccess, (apiCall) => {
+  console.log('请求成功提示已显示')
+})
+
+// 监听请求失败
+ApiCall.emitter.on(ApiEvents.HintFail, (apiCall) => {
+  console.log('请求失败提示已显示')
+})
+
+// 监听 401 未授权
+ApiCall.emitter.on(ApiEvents.Unauthorized, (apiCall) => {
+  // 处理登出逻辑
+})
+```
+
+## 生成的 API 类结构
+
+每个 API 类继承自 `ApiCall<ReqType, ResType>`：
+
+```typescript
+export class ApiGetUser extends ApiCall<GetUserReq, GetUserRes> {
+  path = '/api/user/{id}'
+  method: MoMethod = 'GET'
+  auth = true
+}
+```
+
+## 项目链接
+
+- Gitee: https://gitee.com/ymoo/moyan-api
+- npm: https://www.npmjs.com/package/moyan-api

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "moyan-api",
-  "version": "1.0.80",
+  "version": "1.0.82",
   "description": "使用OpenApi 生成TypeScript的api调用skd",
   "main": "./dist/index.js",
   "types": "src",