Merge pull request #144 from openapi-ui/main

docs: enrich readme

Author: rookie-luochao

.changeset/proud-melons-dress.md

@@ -0,0 +1,5 @@
+---
+'openapi-ts-request': patch
+---
+
+docs: enrich readme files

.changeset/sharp-numbers-film.md

@@ -0,0 +1,5 @@
+---
+'openapi-ts-request': patch
+---
+
+docs: update readme

README-en_US.md

@@ -4,9 +4,16 @@
 
 English | <a href="https://github.com/openapi-ui/openapi-ts-request/blob/master/README.md">简体中文</a>
 
-Generate TS interfaces, request client, request mock service, enum, type field label, JSON Schemas based on [Swagger2/OpenAPI3/Apifox](https://swagger.io/blog/news/whats-new-in-openapi-3-0/) specification
+based on [Swagger2/OpenAPI3/Apifox](https://swagger.io/blog/news/whats-new-in-openapi-3-0/) specification Generate
 
-文档：[use docs](https://github.com/openapi-ui/openapi-ts-request/issues/100)
+- TS interfaces
+- request client
+- request mock service
+- enum and enum translation
+- type field label
+- JSON Schemas
+
+docs：[use docs](https://github.com/openapi-ui/openapi-ts-request/issues/100)
 
 ## Features
 
@@ -38,6 +45,8 @@ create `openapi-ts-request.config.ts` file in the project root directory
 import type { GenerateServiceProps } from 'openapi-ts-request';
 
 export default {
+  // schemaPath: './openapi.json', // local openapi file
+  // serversPath: './src/apis', // interface storage path
   schemaPath: 'http://petstore.swagger.io/v2/swagger.json',
 } as GenerateServiceProps;
 ```
@@ -61,12 +70,47 @@ export default [
 
 add the command in `script` of `package.json`: `"openapi": "openapi-ts",`
 
-generate result:
+run:
 
 ```bash
 npm run openapi
 ```
 
+run:
+
+```bash
+src/apis/index.ts #interface entry file
+src/apis/types.ts #type definition file
+src/apis/app #app interface
+```
+
+```typescript
+// src/apis/pet.ts
+
+/* eslint-disable */
+// @ts-ignore
+import request from 'axios';
+
+import * as API from './types';
+
+/** Update an existing pet PUT /pet */
+export async function updatePet(
+  body: API.Pet,
+  options?: { [key: string]: unknown }
+) {
+  return request<unknown>(`/pet`, {
+    method: 'PUT',
+    headers: {
+      'Content-Type': 'application/json',
+    },
+    data: body,
+    ...(options || {}),
+  });
+}
+
+// ... more interfaces
+```
+
 ### JS
 
 create a new `openapi-ts-request.config.js` file in any directory `xxx/xxx`
@@ -82,7 +126,7 @@ generateService({
 
 add the command in `script` of `package.json`: `"openapi": "node xxx/xxx/openapi-ts-request.config.js"`
 
-generate result:
+run:
 
 ```bash
 npm run openapi
@@ -103,7 +147,7 @@ generateService({
 
 add the command in `script` of `package.json`: `"openapi": "ts-node xxx/xxx/openapi-ts-request.config.ts",`
 
-generate result:
+run:
 
 ```bash
 npm run openapi
@@ -160,7 +204,7 @@ $ openapi --help
     -h, --help                         display help for command
 ```
 
-generate result:
+run:
 
 ```bash
 openapi -i ./spec.json -o ./apis
@@ -171,7 +215,7 @@ openapi -i ./spec.json -o ./apis
 | props | required | type | default | remark |
 | --- | --- | --- | --- | --- |
 | schemaPath | yes | string | - | Swagger2/OpenAPI3 URL |
-| serversPath | no | string | './src/apis' | the folder path for the generated results |
+| serversPath | no | string | './src/apis' | the folder path for the run results |
 | requestLibPath | no | string | 'axios' | custom request lib path, for example: '@/request', 'node-fetch' |
 | enableLogging | no | boolean | false | open the log |
 | priorityRule | no | string | 'include' | priority rule, include/exclude/both |

README.md

@@ -4,7 +4,14 @@
 
 <a href="https://github.com/openapi-ui/openapi-ts-request/blob/master/README-en_US.md">English</a> | 简体中文
 
-根据 [Swagger2/OpenAPI3/Apifox](https://swagger.io/blog/news/whats-new-in-openapi-3-0/) 文档生成 TS 类型, 客户端请求函数, 模拟请求响应服务, 枚举, 类型字段翻译, JSON Schemas
+根据 [Swagger2/OpenAPI3/Apifox](https://swagger.io/blog/news/whats-new-in-openapi-3-0/) 文档生成:
+
+- TS 类型
+- 客户端请求函数
+- 模拟请求响应服务
+- 枚举和枚举翻译
+- 类型字段翻译
+- JSON Schemas
 
 文档：[使用手册](https://github.com/openapi-ui/openapi-ts-request/issues/100)
 
@@ -38,6 +45,8 @@ pnpm i openapi-ts-request -D
 import type { GenerateServiceProps } from 'openapi-ts-request';
 
 export default {
+  // schemaPath: './openapi.json', // 本地openapi文件
+  // serversPath: './src/apis', // 接口存放路径
   schemaPath: 'http://petstore.swagger.io/v2/swagger.json',
 } as GenerateServiceProps;
 ```
@@ -61,12 +70,47 @@ export default [
 
 在 `package.json` 的 `script` 中添加命令: `"openapi": "openapi-ts",`
 
-生成结果：
+运行：
 
 ```bash
 npm run openapi
 ```
 
+生成的接口：
+
+```bash
+src/apis/index.ts #接口入口文件
+src/apis/types.ts #类型定义文件
+src/apis/pet.ts #接口文件
+```
+
+```typescript
+// src/apis/pet.ts
+
+/* eslint-disable */
+// @ts-ignore
+import request from 'axios';
+
+import * as API from './types';
+
+/** Update an existing pet PUT /pet */
+export async function updatePet(
+  body: API.Pet,
+  options?: { [key: string]: unknown }
+) {
+  return request<unknown>(`/pet`, {
+    method: 'PUT',
+    headers: {
+      'Content-Type': 'application/json',
+    },
+    data: body,
+    ...(options || {}),
+  });
+}
+
+// ... 其他接口
+```
+
 ### JS
 
 任意目录 `xxx/xxx` 新建 `openapi-ts-request.config.js`
@@ -82,7 +126,7 @@ generateService({
 
 在 `package.json` 的 `script` 中添加命令: `"openapi": "node xxx/xxx/openapi-ts-request.config.js"`
 
-生成结果：
+运行：
 
 ```bash
 npm run openapi
@@ -103,7 +147,7 @@ generateService({
 
 在 `package.json` 的 `script` 中添加命令: `"openapi": "ts-node xxx/xxx/openapi-ts-request.config.ts",`
 
-生成结果：
+运行：
 
 ```bash
 npm run openapi
@@ -160,7 +204,7 @@ $ openapi --help
     -h, --help                         display help for command
 ```
 
-生成结果：
+运行：
 
 ```bash
 openapi --i ./spec.json --o ./apis
@@ -171,7 +215,7 @@ openapi --i ./spec.json --o ./apis
 | 属性 | 必填 | 类型 | 默认值 | 说明 |
 | --- | --- | --- | --- | --- |
 | schemaPath | 是 | string | - | Swagger2/OpenAPI3 地址 |
-| serversPath | 否 | string | './src/apis' | 生成结果的文件夹路径 |
+| serversPath | 否 | string | './src/apis' | 运行结果文件夹路径 |
 | requestLibPath | 否 | string | 'axios' | 自定义请求方法路径，例如：'@/request'、'node-fetch' |
 | enableLogging | 否 | boolean | false | 是否开启日志 |
 | priorityRule | 否 | string | 'include' | 模式规则，可选include/exclude/both |