openapi-ts-request 0.3.3 → 0.3.4
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +67 -48
- package/dist/index.d.ts +10 -10
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,20 +1,22 @@
|
|
|
1
|
-
##
|
|
1
|
+
## 介绍
|
|
2
2
|
|
|
3
3
|
[](https://github.com/openapi-ui/openapi-ts-request)
|
|
4
4
|
[](https://www.npmjs.com/package/openapi-ts-request)
|
|
5
5
|
|
|
6
6
|
|
|
7
|
-
|
|
7
|
+
<a href="https://github.com/openapi-ui/openapi-ts-request/blob/master/README-en_US.md">English</a> | 简体中文
|
|
8
8
|
|
|
9
|
-
|
|
9
|
+
根据 [Swagger2/OpenAPI3](https://swagger.io/blog/news/whats-new-in-openapi-3-0/) 文档生成 TS 类型, 客户端请求函数, 模拟请求响应服务, 枚举, 类型字段翻译, JSON Schemas
|
|
10
10
|
|
|
11
|
-
|
|
12
|
-
* generate TypeScript interface, reuquest client, request mock service, enum, type field label, JSON Schemas
|
|
13
|
-
* support custom request function, Fetch、Axios、Uniapp-Request、Node.js、XHR client available
|
|
14
|
-
* support filter specification by tags
|
|
15
|
-
* support JSON specification
|
|
11
|
+
## 功能
|
|
16
12
|
|
|
17
|
-
|
|
13
|
+
* 支持 Swagger2.0/OpenAPI 3.0,3.1 定义
|
|
14
|
+
* 生成 TS 类型, 请求客户端, 请求模拟服务, 枚举, 类型字段翻译, JSON Schemas
|
|
15
|
+
* 支持自定义请求工具函数, 支持 Fetch、Axios、UniApp-Request、Node.js、XHR 客户端
|
|
16
|
+
* 支持通过 tags 过滤生成结果
|
|
17
|
+
* 支持 JSON 定义文件
|
|
18
|
+
|
|
19
|
+
## 使用
|
|
18
20
|
|
|
19
21
|
```bash
|
|
20
22
|
npm i openapi-ts-request --save-dev
|
|
@@ -33,7 +35,7 @@ export default {
|
|
|
33
35
|
}
|
|
34
36
|
```
|
|
35
37
|
|
|
36
|
-
|
|
38
|
+
支持传入数组配置进行生成
|
|
37
39
|
|
|
38
40
|
```ts
|
|
39
41
|
export default [
|
|
@@ -48,9 +50,9 @@ export default [
|
|
|
48
50
|
]
|
|
49
51
|
```
|
|
50
52
|
|
|
51
|
-
在 ```package.json``` 的 ```script```
|
|
53
|
+
在 ```package.json``` 的 ```script``` 中添加命令: ```"openapi": "openapi-ts-request",```
|
|
52
54
|
|
|
53
|
-
|
|
55
|
+
生成结果：
|
|
54
56
|
|
|
55
57
|
```bash
|
|
56
58
|
npm run openapi
|
|
@@ -69,9 +71,9 @@ generateService({
|
|
|
69
71
|
})
|
|
70
72
|
```
|
|
71
73
|
|
|
72
|
-
在 ```package.json``` 的 ```script```
|
|
74
|
+
在 ```package.json``` 的 ```script``` 中添加命令: ```"openapi": "node xxx/xxx/openapi-ts-request.config.js"```
|
|
73
75
|
|
|
74
|
-
|
|
76
|
+
生成结果：
|
|
75
77
|
|
|
76
78
|
```bash
|
|
77
79
|
npm run openapi
|
|
@@ -90,47 +92,47 @@ generateService({
|
|
|
90
92
|
})
|
|
91
93
|
```
|
|
92
94
|
|
|
93
|
-
在 ```package.json``` 的 ```script```
|
|
95
|
+
在 ```package.json``` 的 ```script``` 中添加命令: ```"openapi": "ts-node xxx/xxx/openapi-ts-request.config.ts",```
|
|
96
|
+
|
|
97
|
+
生成结果：
|
|
94
98
|
|
|
95
|
-
生成 api
|
|
96
99
|
```bash
|
|
97
100
|
npm run openapi
|
|
98
101
|
```
|
|
99
102
|
|
|
100
|
-
##
|
|
101
|
-
|
|
102
|
-
|
|
|
103
|
-
|
|
|
104
|
-
| schemaPath
|
|
105
|
-
| serversPath
|
|
106
|
-
| requestLibPath
|
|
107
|
-
| allowedTags
|
|
108
|
-
| requestOptionsType
|
|
109
|
-
| requestImportStatement
|
|
110
|
-
| apiPrefix
|
|
111
|
-
| isDisplayTypeLabel
|
|
112
|
-
| isGenJsonSchemas
|
|
113
|
-
|
|
|
114
|
-
|
|
|
115
|
-
|
|
|
116
|
-
|
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
|
122
|
-
|
|
|
123
|
-
|
|
|
124
|
-
|
|
|
125
|
-
|
|
|
126
|
-
|
|
|
127
|
-
|
|
|
128
|
-
| customFileNames | (<br>operationObject: OperationObject,<br>apiPath: string,<br>apiMethod: string,<br>) => string[] | 自定义生成文件名，可返回多个，表示生成多个文件. <br> *返回为空，则使用默认的获取方法获取* |
|
|
103
|
+
## 参数
|
|
104
|
+
|
|
105
|
+
| 属性 | 必填 | 类型 | 默认值 | 说明 |
|
|
106
|
+
| ---------------------- | ----- | -------- | ------------ | ------ |
|
|
107
|
+
| schemaPath | 是 | string | - | Swagger2/OpenAPI3 地址 |
|
|
108
|
+
| serversPath | 否 | string | './src/apis' | 生成结果的文件夹路径 |
|
|
109
|
+
| requestLibPath | 否 | string | - | 自定义请求方法路径，例如：'@/request', 'node-fetch' |
|
|
110
|
+
| allowedTags | 否 | string[] | - | 根据指定的 tags 生成结果 |
|
|
111
|
+
| requestOptionsType | 否 | string | '{ [key: string]: unknown }' | 自定义请求方法 options 参数类型 |
|
|
112
|
+
| requestImportStatement | 否 | string | - | 自定义请求方法表达式，例如："const request = require('@/request')" |
|
|
113
|
+
| apiPrefix | 否 | string | - | api path的前缀，例如：'api'(动态变量), "'api'"(字符串) |
|
|
114
|
+
| isDisplayTypeLabel | 否 | boolean | false | 是否生成 type 对应的label |
|
|
115
|
+
| isGenJsonSchemas | 否 | boolean | false | 是否生成 JSON Schemas |
|
|
116
|
+
| mockFolder | 否 | string | './mocks' | mock文件路径 |
|
|
117
|
+
| nullable | 否 | boolean | false | 使用 null 代替可选 |
|
|
118
|
+
| isCamelCase | 否 | boolean | true | 小驼峰命名文件和请求函数 |
|
|
119
|
+
| hook | 否 | [Custom Hook](#Custom-Hook) | - | 自定义 hook |
|
|
120
|
+
|
|
121
|
+
## 自定义 Hook
|
|
122
|
+
|
|
123
|
+
| 属性 | 类型 | 说明 |
|
|
124
|
+
| ---------------------- | ---- | ------------------ |
|
|
125
|
+
| afterOpenApiDataInited | (openAPIData: OpenAPIObject) => OpenAPIObject | 自定义 OpenAPI 数据 |
|
|
126
|
+
| customFunctionName | (data: APIDataType) => string | 自定义请求方法函数名称 |
|
|
127
|
+
| customTypeName | (data: APIDataType) => string | 自定义类型名称 |
|
|
128
|
+
| customClassName | (tagName: string) => string | 自定义标签名 |
|
|
129
|
+
| customType | (<br>schemaObject: SchemaObject \| ReferenceObject,<br>namespace: string,<br>originGetType:(schemaObject: SchemaObject \| ReferenceObject, namespace: string) => string,<br>) => string | 自定义类型 <br> *返回非字符串将使用默认方法获取type* |
|
|
130
|
+
| customFileNames | (<br>operationObject: OperationObject,<br>apiPath: string,<br>apiMethod: string,<br>) => string[] | 自定义生成的请求客户端文件名称，可以返回多个文件名称的数组(表示生成多个文件). <br> *返回为空，则使用默认的方法获取* |
|
|
129
131
|
|
|
130
132
|
## JSON Schemas
|
|
131
133
|
|
|
132
|
-
- 默认生成 [components.schemas](https://spec.openapis.org/oas/latest.html#components-object) 下面的 JSON Schemas
|
|
133
|
-
- 提供一个解析 schema
|
|
134
|
+
- 默认生成 [components.schemas](https://spec.openapis.org/oas/latest.html#components-object) 下面的 JSON Schemas，[paths](https://spec.openapis.org/oas/latest.html#paths-object) 对应的 JSON Schemas 目前需自行解析
|
|
135
|
+
- 提供一个解析 schema 的函数，用于将 `$ref`，`$allOf` 的引用填充到 `当前schema`
|
|
134
136
|
|
|
135
137
|
```ts
|
|
136
138
|
export declare function patchSchema<T extends object>(schema: ISchemaObject, schemas: ComponentsObject["schemas"]): T;
|
|
@@ -140,7 +142,24 @@ export declare function patchSchema<T extends object>(schema: ISchemaObject, sch
|
|
|
140
142
|
|
|
141
143
|
目前使用 [mockjs](http://mockjs.com) 生成 mock 数据，mocks 文件启动需要借助 [@umijs/server](https://umijs.org/docs/guides/mock)，后面会寻找其他方案以达到更好的 mock 体验
|
|
142
144
|
|
|
143
|
-
##
|
|
145
|
+
## 贡献
|
|
146
|
+
|
|
147
|
+
### 环境要求
|
|
148
|
+
|
|
149
|
+
* node 18+
|
|
150
|
+
* pnpm 9+
|
|
151
|
+
|
|
152
|
+
### 提交 Pull Request
|
|
153
|
+
|
|
154
|
+
1. 熟悉 [Pull Request]("https://help.github.com/articles/using-pull-requests") 规范
|
|
155
|
+
2. fork 此仓库
|
|
156
|
+
3. 开一个新分支修改代码：`git checkout -b my-branch main`
|
|
157
|
+
4. 确保你的代码可以通过所有测试用例(新增功能需要添加新的功能测试用例)：`pnpm test`
|
|
158
|
+
5. 创建 changeset 文件通过命令：`pnpm changeset`
|
|
159
|
+
6. 使用 commit 提交你的修改(需遵循 commitlint 规范)
|
|
160
|
+
7. 发起 Pull Request
|
|
161
|
+
|
|
162
|
+
## 感谢
|
|
144
163
|
|
|
145
164
|
- [openapi2typescript](https://github.com/chenshuai2144/openapi2typescript)
|
|
146
165
|
|
package/dist/index.d.ts
CHANGED
|
@@ -3,7 +3,7 @@ import { ComponentsObject, OpenAPIObject, OperationObject, ReferenceObject, Sche
|
|
|
3
3
|
export * from './generator/patchSchema';
|
|
4
4
|
export type GenerateServiceProps = {
|
|
5
5
|
/**
|
|
6
|
-
*
|
|
6
|
+
* Swagger2/OpenAPI3 地址
|
|
7
7
|
*/
|
|
8
8
|
schemaPath: string;
|
|
9
9
|
/**
|
|
@@ -49,7 +49,7 @@ export type GenerateServiceProps = {
|
|
|
49
49
|
isGenJsonSchemas?: boolean;
|
|
50
50
|
/**
|
|
51
51
|
* response中数据字段
|
|
52
|
-
* example: ['result'
|
|
52
|
+
* for example: ['result']
|
|
53
53
|
*/
|
|
54
54
|
dataFields?: string[];
|
|
55
55
|
/**
|
|
@@ -84,7 +84,7 @@ export type GenerateServiceProps = {
|
|
|
84
84
|
customTypeName?: (data: APIDataType) => string;
|
|
85
85
|
/** 自定义 options 默认值 */
|
|
86
86
|
customOptionsDefaultValue?: (data: OperationObject) => Record<string, any> | undefined;
|
|
87
|
-
/**
|
|
87
|
+
/** 自定义 tag 名称 */
|
|
88
88
|
customClassName?: (tagName: string) => string;
|
|
89
89
|
/**
|
|
90
90
|
* 自定义获取type hook
|
|
@@ -103,14 +103,14 @@ export type GenerateServiceProps = {
|
|
|
103
103
|
originGetType: (schemaObject: SchemaObject, namespace: string) => string;
|
|
104
104
|
}) => string;
|
|
105
105
|
/**
|
|
106
|
-
*
|
|
107
|
-
*
|
|
106
|
+
* 自定义生成文件名，可返回多个，表示生成多个文件;
|
|
107
|
+
* 返回为空，则使用默认的获取方法获取;
|
|
108
108
|
* @example 使用operationId生成文件名
|
|
109
|
-
* function customFileNames(operationObject,apiPath){
|
|
110
|
-
* const operationId=operationObject.operationId;
|
|
109
|
+
* function customFileNames(operationObject, apiPath){
|
|
110
|
+
* const operationId = operationObject.operationId;
|
|
111
111
|
* if (!operationId) {
|
|
112
112
|
* console.warn('[Warning] no operationId', apiPath);
|
|
113
|
-
* return;
|
|
113
|
+
* return null;
|
|
114
114
|
* }
|
|
115
115
|
* const res = operationId.split('_');
|
|
116
116
|
* if (res.length > 1) {
|
|
@@ -124,11 +124,11 @@ export type GenerateServiceProps = {
|
|
|
124
124
|
* if (controllerName) {
|
|
125
125
|
* return [controllerName];
|
|
126
126
|
* }
|
|
127
|
-
* return;
|
|
127
|
+
* return null;
|
|
128
128
|
* }
|
|
129
129
|
* }
|
|
130
130
|
*/
|
|
131
|
-
customFileNames?: (operationObject: OperationObject, apiPath: string, apiMethod: string) => string[];
|
|
131
|
+
customFileNames?: (operationObject: OperationObject, apiPath: string, apiMethod: string) => string[] | null;
|
|
132
132
|
};
|
|
133
133
|
};
|
|
134
134
|
export declare function generateService({ requestLibPath, schemaPath, mockFolder, allowedTags, ...rest }: GenerateServiceProps): Promise<void>;
|
package/package.json
CHANGED