Skip to content

Commit 788eb6b

Browse files
rookie-luochaorookie-luochao
committed
docs: add English readme
1 parent fbdd48a commit 788eb6b

File tree

4 files changed

+246
-58
lines changed

4 files changed

+246
-58
lines changed

‎.changeset/great-gifts-obey.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
---
2+
'openapi-ts-request': patch
3+
---
4+
5+
docs: add English readme

‎README-en_US.md‎

Lines changed: 164 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,164 @@
1+
## Introduce
2+
3+
[![GitHub Repo stars](https://img.shields.io/github/stars/openapi-ui/openapi-ts-request?style=social)](https://github.com/openapi-ui/openapi-ts-request)
4+
[![npm (scoped)](https://img.shields.io/npm/v/openapi-ts-request)](https://www.npmjs.com/package/openapi-ts-request)
5+
![GitHub tag](https://img.shields.io/github/v/tag/openapi-ui/openapi-ts-request?include_prereleases)
6+
7+
English | <a href="https://github.com/openapi-ui/openapi-ts-request/blob/master/README.md">简体中文</a>
8+
9+
Generate TS interfaces, request client, request mock service, enum, type field label, JSON Schemas based on [Swagger2/OpenAPI3](https://swagger.io/blog/news/whats-new-in-openapi-3-0/) specification
10+
11+
## Features
12+
13+
* support Swagger2.0/OpenAPI 3.0,3.1 specification
14+
* generate TypeScript interface, reuquest client, request mock service, enum, type field label, JSON Schemas
15+
* support custom request function, Fetch、Axios、UniApp-request、Node.js、XHR client available
16+
* support filter generate result by tags
17+
* support JSON specification
18+
19+
## Usage
20+
21+
```bash
22+
npm i openapi-ts-request --save-dev
23+
24+
pnpm i openapi-ts-request -D
25+
```
26+
27+
### CosmiConfig
28+
29+
create ```openapi-ts-request.config.ts``` file in the project root directory
30+
> the config file also supports ***.openapi-ts-request.ts***, ***openapi-ts-request.config.cjs*** format, reference [cosmiconfig](https://github.com/cosmiconfig/cosmiconfig?tab=readme-ov-file#cosmiconfig)
31+
32+
```ts
33+
export default {
34+
schemaPath: 'http://petstore.swagger.io/v2/swagger.json',
35+
}
36+
```
37+
38+
support passing in array config for generate
39+
40+
```ts
41+
export default [
42+
{
43+
schemaPath: 'http://app.swagger.io/v2/swagger.json',
44+
serversPath: './src/apis/app',
45+
},
46+
{
47+
schemaPath: 'http://auth.swagger.io/v2/swagger.json',
48+
serversPath: './src/apis/auth',
49+
}
50+
]
51+
```
52+
53+
add the command in ```script``` of ```package.json```: ```"openapi": "openapi-ts-request",```
54+
55+
generate result:
56+
57+
```bash
58+
npm run openapi
59+
```
60+
61+
### JS
62+
63+
create a new ```openapi-ts-request.config.js``` file in any directory ```xxx/xxx```
64+
65+
```ts
66+
const { generateService } = require('openapi-ts-request')
67+
68+
generateService({
69+
schemaPath: 'http://petstore.swagger.io/v2/swagger.json',
70+
serversPath: './apis',
71+
})
72+
```
73+
74+
add the command in ```script``` of ```package.json```: ```"openapi": "node xxx/xxx/openapi-ts-request.config.js"```
75+
76+
generate result:
77+
78+
```bash
79+
npm run openapi
80+
```
81+
82+
### TS
83+
84+
create a new ```openapi-ts-request.config.ts``` file in any directory ```xxx/xxx```
85+
86+
```ts
87+
const { generateService } = require('openapi-ts-request')
88+
89+
generateService({
90+
schemaPath: 'http://petstore.swagger.io/v2/swagger.json',
91+
serversPath: './apis',
92+
})
93+
```
94+
95+
add the command in ```script``` of ```package.json```: ```"openapi": "ts-node xxx/xxx/openapi-ts-request.config.ts",```
96+
97+
generate result:
98+
99+
```bash
100+
npm run openapi
101+
```
102+
103+
## Parameter
104+
105+
| props | required | type | default | remark |
106+
| ---------------------- | -------- | -------- | ------------ | ------- |
107+
| schemaPath | yes | string | - | Swagger2/OpenAPI3 URL |
108+
| serversPath | no | string | './src/apis' | the folder path for the generated results |
109+
| requestLibPath | no | string | - | custom request lib path, for example: '@/request', 'node-fetch' |
110+
| allowedTags | no | string[] | - | generate results from allowed tags |
111+
| requestOptionsType | no | string | '{ [key: string]: unknown }' | custom request method options parameter type |
112+
| requestImportStatement | no | string | - | custom request import statement, for example: "const request = require('@/request')" |
113+
| apiPrefix | no | string | - | custom the prefix of the api path，例如：'api'(variable), "'api'"(string) |
114+
| isDisplayTypeLabel | no | boolean | false | generate label matching type field |
115+
| isGenJsonSchemas | no | boolean | false | generate JSON Schemas |
116+
| mockFolder | no | string | './mocks' | mock file path |
117+
| nullable | no | boolean | false | null instead of optional |
118+
| isCamelCase | no | boolean | true | camelCase naming of controller files and request client |
119+
| hook | no | [Custom Hook](#Custom-Hook) | - | custom hook |
120+
121+
## Custom Hook
122+
123+
| props | type | remark |
124+
| ---------------------- | ---- | ----------------- |
125+
| afterOpenApiDataInited | (openAPIData: OpenAPIObject) => OpenAPIObject | custom OpenAPI data |
126+
| customFunctionName | (data: APIDataType) => string | custom request client function name |
127+
| customTypeName | (data: APIDataType) => string | custom type name |
128+
| customClassName | (tagName: string) => string | custom tag name |
129+
| customType | (<br>schemaObject: SchemaObject \| ReferenceObject,<br>namespace: string,<br>originGetType:(schemaObject: SchemaObject \| ReferenceObject, namespace: string) => string,<br>) => string | custom type <br> *returning a non-string will use the default method to get the type* |
130+
| customFileNames | (<br>operationObject: OperationObject,<br>apiPath: string,<br>apiMethod: string,<br>) => string[] | custom generate request client controller file name, can return multiple: generate multiple files. <br> *if the return value is empty, the default getFileNames is used* |
131+
132+
## JSON Schemas
133+
134+
- default generate JSON Schemas based on [components.schemas](https://spec.openapis.org/oas/latest.html#components-object), JSON Schemas corresponding to [paths](https://spec.openapis.org/oas/latest.html#paths-object) currently need to be parsed by yourself
135+
- provide a schema parsing function to fill the references of `$ref` and `$allOf` into `current schema`
136+
137+
```ts
138+
export declare function patchSchema<T extends object>(schema: ISchemaObject, schemas: ComponentsObject["schemas"]): T;
139+
```
140+
141+
## Mock
142+
143+
currently using [mockjs](http://mockjs.com) to generate mock data, the mocks file startup needs to rely on [@umijs/server](https://umijs.org/docs/guides/mock), we will look for other solutions later to achieve a better mock experience
144+
145+
## Contribute
146+
147+
### Development Environment
148+
149+
* node 18+
150+
* pnpm 9+
151+
152+
### Submit Pull Request
153+
154+
1. learn [Pull Request]("https://help.github.com/articles/using-pull-requests") specification
155+
2. fork this repository
156+
3. create a new branch to modify the code：`git checkout -b my-branch main`
157+
4. make sure your code passes all test cases (new functional test cases need to be added for new features)：`pnpm test`
158+
5. create a changeset file using the command：`pnpm changeset`
159+
6. submit your changes using commit (must follow commitlint specification)
160+
7. submit Pull Request
161+
162+
## Thanks
163+
164+
- [openapi2typescript](https://github.com/chenshuai2144/openapi2typescript)

‎README.md‎

Lines changed: 67 additions & 48 deletions
Original file line numberDiff line numberDiff line change
@@ -1,20 +1,22 @@
1-
## Introduce
1+
## 介绍
22

33
[![GitHub Repo stars](https://img.shields.io/github/stars/openapi-ui/openapi-ts-request?style=social)](https://github.com/openapi-ui/openapi-ts-request)
44
[![npm (scoped)](https://img.shields.io/npm/v/openapi-ts-request)](https://www.npmjs.com/package/openapi-ts-request)
55
![GitHub tag](https://img.shields.io/github/v/tag/openapi-ui/openapi-ts-request?include_prereleases)
66

7-
根据 [Swagger2/OpenAPI3](https://swagger.io/blog/news/whats-new-in-openapi-3-0/) 文档生成 ts 类型, request client 请求代码, request mock 服务, 枚举, type 字段翻译, JSON Schemas
7+
<a href="https://github.com/openapi-ui/openapi-ts-request/blob/master/README-en_US.md">English</a> | 简体中文
88

9-
## Features
9+
根据 [Swagger2/OpenAPI3](https://swagger.io/blog/news/whats-new-in-openapi-3-0/) 文档生成 TS 类型, 客户端请求函数, 模拟请求响应服务, 枚举, 类型字段翻译, JSON Schemas
1010

11-
* support Swagger2.0/OpenAPI 3.0,3.1 specification
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+
## 功能
1612

17-
## Usage
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+
## 使用
1820

1921
```bash
2022
npm i openapi-ts-request --save-dev
@@ -33,7 +35,7 @@ export default {
3335
}
3436
```
3537

36-
如果项目有多个生成需求，支持传入数组配置
38+
支持传入数组配置进行生成
3739

3840
```ts
3941
export default [
@@ -48,9 +50,9 @@ export default [
4850
]
4951
```
5052

51-
在 ```package.json``` 的 ```script``` 中添加 api: ```"openapi": "openapi-ts-request",```
53+
在 ```package.json``` 的 ```script``` 中添加命令: ```"openapi": "openapi-ts-request",```
5254

53-
生成 api
55+
生成结果：
5456

5557
```bash
5658
npm run openapi
@@ -69,9 +71,9 @@ generateService({
6971
})
7072
```
7173

72-
在 ```package.json``` 的 ```script``` 中添加 script: ```"openapi": "node xxx/xxx/openapi-ts-request.config.js"```
74+
在 ```package.json``` 的 ```script``` 中添加命令: ```"openapi": "node xxx/xxx/openapi-ts-request.config.js"```
7375

74-
生成 api
76+
生成结果：
7577

7678
```bash
7779
npm run openapi
@@ -90,47 +92,47 @@ generateService({
9092
})
9193
```
9294

93-
在 ```package.json``` 的 ```script``` 中添加 api: ```"openapi": "ts-node xxx/xxx/openapi-ts-request.config.ts",```
95+
在 ```package.json``` 的 ```script``` 中添加命令: ```"openapi": "ts-node xxx/xxx/openapi-ts-request.config.ts",```
96+
97+
生成结果：
9498

95-
生成 api
9699
```bash
97100
npm run openapi
98101
```
99102

100-
## Parameter
101-
102-
| 属性 | 必填 | 备注 | 类型 | 默认值 |
103-
| ---- | ---- | ---- | ---- | - |
104-
| schemaPath | 是 | Swagger 2.0 或 OpenAPI 3.0 的地址 | string | - |
105-
| serversPath | 否 | 生成的文件夹的路径 | string | './src/apis' |
106-
| requestLibPath | 否 | 自定义请求方法路径 | string | - |
107-
| allowedTags | 否 | 生成指定 tags 下面的 api | string[] | - |
108-
| requestOptionsType | 否 | 自定义请求方法 options 参数类型 | string | '{ [key: string]: unknown }' |
109-
| requestImportStatement | 否 | 自定义请求方法表达式，例如：'@/request' | string | - |
110-
| apiPrefix | 否 | api 的前缀，例如：'api'(动态变量), 指定字符串("'api'") | string | - |
111-
| isDisplayTypeLabel | 否 | 是否生成 type 对应的label | boolean | false |
112-
| isGenJsonSchemas | 否 | 是否生成 JSON Schemas | boolean | false |
113-
| dataFields | 否 | 定义 response 中数据字段类型 | string[] | - |
114-
| mockFolder | 否 | mock目录 | string | './mocks' |
115-
| nullable | 否 | 使用null代替可选 | boolean | false |
116-
| isCamelCase | 否 | 小驼峰命名文件和请求函数 | boolean | true |
117-
| hook | 否 | 自定义 hook | [Custom Hook](#Custom-Hook) | - |
118-
119-
## Custom Hook
120-
121-
| 属性 | 类型 | 说明 |
122-
| -------------- | ---- | ------------------ |
123-
| afterOpenApiDataInited | (openAPIData: OpenAPIObject) => OpenAPIObject | 自定义OpenAPI数据 |
124-
| customFunctionName | (data: APIDataType) => string | 自定义请求方法函数名称 |
125-
| customTypeName | (data: APIDataType) => string | 自定义类型名称 |
126-
| customClassName | (tagName: string) => string | 自定义类名 |
127-
| customType | (<br>schemaObject: SchemaObject \| ReferenceObject,<br>namespace: string,<br>originGetType:(schemaObject: SchemaObject \| ReferenceObject, namespace: string) => string,<br>) => string | 自定义获取类型 <br> *返回非字符串将使用默认方法获取type* |
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> *返回为空，则使用默认的方法获取* |
129131

130132
## JSON Schemas
131133

132-
- 默认生成 [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 目前需自行解析
133-
- 提供一个解析 schema 的函数用于将 `$ref`, `$allOf` 的引用填充到 `当前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`
134136

135137
```ts
136138
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
140142

141143
目前使用 [mockjs](http://mockjs.com) 生成 mock 数据，mocks 文件启动需要借助 [@umijs/server](https://umijs.org/docs/guides/mock)，后面会寻找其他方案以达到更好的 mock 体验
142144

143-
## Thanks
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+
## 感谢
144163

145164
- [openapi2typescript](https://github.com/chenshuai2144/openapi2typescript)
146165

0 commit comments

Comments
 (0)