Skip to content

Commit cdecb3f

Browse files
rookie-luochaorookie-luochao
committed
docs: update readme
1 parent 0eb336b commit cdecb3f

File tree

5 files changed

+121
-111
lines changed

5 files changed

+121
-111
lines changed

‎.changeset/thirty-lemons-call.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: update readme

‎README-en_US.md‎

Lines changed: 59 additions & 57 deletions
Original file line numberDiff line numberDiff line change
@@ -1,21 +1,19 @@
11
## Introduce
22

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)
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) [![npm (scoped)](https://img.shields.io/npm/v/openapi-ts-request)](https://www.npmjs.com/package/openapi-ts-request) ![GitHub tag](https://img.shields.io/github/v/tag/openapi-ui/openapi-ts-request?include_prereleases)
64

7-
English | <a href="https://github.com/openapi-ui/openapi-ts-request/blob/master/README.md">简体中文</a>
5+
English | <a href="https://github.com/openapi-ui/openapi-ts-request/blob/master/README.md">简体中文</a>
86

97
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
108

119
## Features
1210

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 work with npx, CLI, Nodejs
16-
* support custom request function, Fetch、Axios、UniApp-request、Node.js、XHR client available
17-
* support filter generate result by tags
18-
* support JSON specification
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 work with npx, CLI, Nodejs
14+
- support custom request function, Fetch、Axios、UniApp-request、Node.js、XHR client available
15+
- support filter generate result by tags
16+
- support JSON specification
1917

2018
## Usage
2119

@@ -29,21 +27,22 @@ pnpm i openapi-ts-request -D
2927

3028
### CosmiConfig
3129

32-
create ```openapi-ts-request.config.ts``` file in the project root directory
33-
> 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)
30+
create `openapi-ts-request.config.ts` file in the project root directory
31+
32+
> 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)
3433
3534
```ts
36-
import type { GenerateServiceProps } from 'openapi-ts-request'
35+
import type { GenerateServiceProps } from 'openapi-ts-request';
3736

3837
export default {
3938
schemaPath: 'http://petstore.swagger.io/v2/swagger.json',
40-
} as GenerateServiceProps
39+
} as GenerateServiceProps;
4140
```
4241

4342
support passing in array config for generate
4443

4544
```ts
46-
import type { GenerateServiceProps } from 'openapi-ts-request'
45+
import type { GenerateServiceProps } from 'openapi-ts-request';
4746

4847
export default [
4948
{
@@ -53,55 +52,55 @@ export default [
5352
{
5453
schemaPath: 'http://auth.swagger.io/v2/swagger.json',
5554
serversPath: './src/apis/auth',
56-
}
57-
] as GenerateServiceProps[]
55+
},
56+
] as GenerateServiceProps[];
5857
```
5958

60-
add the command in ```script``` of ```package.json```: ```"openapi": "openapi-ts",```
59+
add the command in `script` of `package.json`: `"openapi": "openapi-ts",`
6160

62-
generate result:
61+
generate result:
6362

6463
```bash
6564
npm run openapi
6665
```
6766

6867
### JS
6968

70-
create a new ```openapi-ts-request.config.js``` file in any directory ```xxx/xxx```
69+
create a new `openapi-ts-request.config.js` file in any directory `xxx/xxx`
7170

7271
```ts
73-
const { generateService } = require('openapi-ts-request')
72+
const { generateService } = require('openapi-ts-request');
7473

7574
generateService({
7675
schemaPath: 'http://petstore.swagger.io/v2/swagger.json',
7776
serversPath: './apis',
78-
})
77+
});
7978
```
8079

81-
add the command in ```script``` of ```package.json```: ```"openapi": "node xxx/xxx/openapi-ts-request.config.js"```
80+
add the command in `script` of `package.json`: `"openapi": "node xxx/xxx/openapi-ts-request.config.js"`
8281

83-
generate result:
82+
generate result:
8483

8584
```bash
8685
npm run openapi
8786
```
8887

8988
### TS
9089

91-
create a new ```openapi-ts-request.config.ts``` file in any directory ```xxx/xxx```
90+
create a new `openapi-ts-request.config.ts` file in any directory `xxx/xxx`
9291

9392
```ts
94-
const { generateService } = require('openapi-ts-request')
93+
const { generateService } = require('openapi-ts-request');
9594

9695
generateService({
9796
schemaPath: 'http://petstore.swagger.io/v2/swagger.json',
9897
serversPath: './apis',
99-
})
98+
});
10099
```
101100

102-
add the command in ```script``` of ```package.json```: ```"openapi": "ts-node xxx/xxx/openapi-ts-request.config.ts",```
101+
add the command in `script` of `package.json`: `"openapi": "ts-node xxx/xxx/openapi-ts-request.config.ts",`
103102

104-
generate result:
103+
generate result:
105104

106105
```bash
107106
npm run openapi
@@ -150,48 +149,51 @@ $ openapi --help
150149
-h, --help display help for command
151150
```
152151

153-
generate result:
152+
generate result:
154153

155154
```bash
156155
openapi -i ./spec.json -o ./apis
157156
```
158157

159158
## Parameter
160159

161-
| props | required | type | default | remark |
162-
| ---------------------- | -------- | -------- | ------------ | ------- |
163-
| schemaPath | yes | string | - | Swagger2/OpenAPI3 URL |
164-
| serversPath | no | string | './src/apis' | the folder path for the generated results |
165-
| requestLibPath | no | string | - | custom request lib path, for example: '@/request', 'node-fetch' |
166-
| allowedTags | no | string[] | - | generate results from allowed tags |
167-
| requestOptionsType | no | string | '{ [key: string]: unknown }' | custom request method options parameter type |
168-
| requestImportStatement | no | string | - | custom request import statement, for example: "const request = require('@/request')" |
169-
| apiPrefix | no | string | - | custom the prefix of the api path, for example: 'api'(variable), "'api'"(string) |
170-
| isDisplayTypeLabel | no | boolean | false | generate label matching type field |
171-
| isGenJsonSchemas | no | boolean | false | generate JSON Schemas |
172-
| mockFolder | no | string | './mocks' | mock file path |
173-
| nullable | no | boolean | false | null instead of optional |
174-
| isCamelCase | no | boolean | true | camelCase naming of controller files and request client |
175-
| hook | no | [Custom Hook](#Custom-Hook) | - | custom hook |
160+
| props | required | type | default | remark |
161+
| --- | --- | --- | --- | --- |
162+
| schemaPath | yes | string | - | Swagger2/OpenAPI3 URL |
163+
| serversPath | no | string | './src/apis' | the folder path for the generated results |
164+
| requestLibPath | no | string | - | custom request lib path, for example: '@/request', 'node-fetch' |
165+
| allowedTags | no | string[] | - | generate results from allowed tags |
166+
| requestOptionsType | no | string | '{ [key: string]: unknown }' | custom request method options parameter type |
167+
| requestImportStatement | no | string | - | custom request import statement, for example: "const request = require('@/request')" |
168+
| apiPrefix | no | string | - | custom the prefix of the api path, for example: 'api'(variable), "'api'"(string) |
169+
| isDisplayTypeLabel | no | boolean | false | generate label matching type field |
170+
| isGenJsonSchemas | no | boolean | false | generate JSON Schemas |
171+
| mockFolder | no | string | './mocks' | mock file path |
172+
| nullable | no | boolean | false | null instead of optional |
173+
| isCamelCase | no | boolean | true | camelCase naming of controller files and request client |
174+
| hook | no | [Custom Hook](#Custom-Hook) | - | custom hook |
176175

177176
## Custom Hook
178177

179-
| props | type | remark |
180-
| ---------------------- | ---- | ----------------- |
181-
| afterOpenApiDataInited | (openAPIData: OpenAPIObject) => OpenAPIObject | custom OpenAPI data |
182-
| customFunctionName | (data: APIDataType) => string | custom request client function name |
183-
| customTypeName | (data: APIDataType) => string | custom type name |
184-
| customClassName | (tagName: string) => string | custom tag name |
185-
| 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* |
186-
| 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* |
178+
| props | type | remark |
179+
| --- | --- | --- |
180+
| afterOpenApiDataInited | (openAPIData: OpenAPIObject) => OpenAPIObject | custom OpenAPI data |
181+
| customFunctionName | (data: APIDataType) => string | custom request client function name |
182+
| customTypeName | (data: APIDataType) => string | custom type name |
183+
| customClassName | (tagName: string) => string | custom tag name |
184+
| 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_ |
185+
| 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_ |
187186

188187
## JSON Schemas
189188

190189
- 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
191190
- provide a schema parsing function to fill the references of `$ref` and `$allOf` into `current schema`
192191

193192
```ts
194-
export declare function patchSchema<T extends object>(schema: ISchemaObject, schemas: ComponentsObject["schemas"]): T;
193+
export declare function patchSchema<T extends object>(
194+
schema: ISchemaObject,
195+
schemas: ComponentsObject['schemas']
196+
): T;
195197
```
196198

197199
## Mock
@@ -202,8 +204,8 @@ currently using [mockjs](http://mockjs.com) to generate mock data, the mocks fil
202204

203205
### Development Environment
204206

205-
* node 18+
206-
* pnpm 9+
207+
- node 18+
208+
- pnpm 9+
207209

208210
### Submit Pull Request
209211

@@ -217,4 +219,4 @@ currently using [mockjs](http://mockjs.com) to generate mock data, the mocks fil
217219

218220
## Thanks
219221

220-
- [openapi2typescript](https://github.com/chenshuai2144/openapi2typescript)
222+
- [openapi2typescript](https://github.com/chenshuai2144/openapi2typescript)

0 commit comments

Comments
 (0)