diff --git a/.changeset/proud-melons-dress.md b/.changeset/proud-melons-dress.md new file mode 100644 index 0000000..10ed9d0 --- /dev/null +++ b/.changeset/proud-melons-dress.md @@ -0,0 +1,5 @@ +--- +'openapi-ts-request': patch +--- + +docs: enrich readme files diff --git a/.changeset/sharp-numbers-film.md b/.changeset/sharp-numbers-film.md new file mode 100644 index 0000000..e0133ea --- /dev/null +++ b/.changeset/sharp-numbers-film.md @@ -0,0 +1,5 @@ +--- +'openapi-ts-request': patch +--- + +docs: update readme diff --git a/README-en_US.md b/README-en_US.md index 9b9e14b..c4f50d9 100644 --- a/README-en_US.md +++ b/README-en_US.md @@ -4,9 +4,16 @@ English | 简体中文 -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(`/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 | diff --git a/README.md b/README.md index 3fc0a25..48d3b0e 100644 --- a/README.md +++ b/README.md @@ -4,7 +4,14 @@ English | 简体中文 -根据 [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(`/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 | diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index b02b117..c401067 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -80,7 +80,7 @@ importers: version: 2.27.10 '@commitlint/cli': specifier: ^19.2.1 - version: 19.6.0(@types/node@20.16.9)(typescript@5.7.2) + version: 19.6.1(@types/node@20.16.9)(typescript@5.7.2) '@commitlint/config-conventional': specifier: ^19.2.2 version: 19.6.0 @@ -122,7 +122,7 @@ importers: version: 9.1.7 lint-staged: specifier: ^15.2.5 - version: 15.2.10 + version: 15.2.11 openapi-types: specifier: ^12.1.3 version: 12.1.3 @@ -261,8 +261,8 @@ packages: '@changesets/write@0.3.2': resolution: {integrity: sha512-kDxDrPNpUgsjDbWBvUo27PzKX4gqeKOlhibaOXDJA6kuBisGqNHv/HwGJrAu8U/dSf8ZEFIeHIPtvSlZI1kULw==} - '@commitlint/cli@19.6.0': - resolution: {integrity: sha512-v17BgGD9w5KnthaKxXnEg6KLq6DYiAxyiN44TpiRtqyW8NSq+Kx99mkEG8Qo6uu6cI5eMzMojW2muJxjmPnF8w==} + '@commitlint/cli@19.6.1': + resolution: {integrity: sha512-8hcyA6ZoHwWXC76BoC8qVOSr8xHy00LZhZpauiD0iO0VYbVhMnED0da85lTfIULxl7Lj4c6vZgF0Wu/ed1+jlQ==} engines: {node: '>=v18'} hasBin: true @@ -294,8 +294,8 @@ packages: resolution: {integrity: sha512-LRo7zDkXtcIrpco9RnfhOKeg8PAnE3oDDoalnrVU/EVaKHYBWYL1DlRR7+3AWn0JiBqD8yKOfetVxJGdEtZ0tg==} engines: {node: '>=v18'} - '@commitlint/load@19.5.0': - resolution: {integrity: sha512-INOUhkL/qaKqwcTUvCE8iIUf5XHsEPCLY9looJ/ipzi7jtGhgmtH7OOFiNvwYgH7mA8osUWOUDV8t4E2HAi4xA==} + '@commitlint/load@19.6.1': + resolution: {integrity: sha512-kE4mRKWWNju2QpsCWt428XBvUH55OET2N4QKQ0bF85qS/XbsRGG1MiTByDNlEVpEPceMkDr46LNH95DtRwcsfA==} engines: {node: '>=v18'} '@commitlint/message@19.5.0': @@ -752,6 +752,14 @@ packages: cosmiconfig: '>=8.2' typescript: '>=4' + cosmiconfig-typescript-loader@6.1.0: + resolution: {integrity: sha512-tJ1w35ZRUiM5FeTzT7DtYWAFFv37ZLqSRkGi2oeCK1gPhvaWjkAtfXvLmvE1pRfxxp9aQo6ba/Pvg1dKj05D4g==} + engines: {node: '>=v18'} + peerDependencies: + '@types/node': '*' + cosmiconfig: '>=9' + typescript: '>=5' + cosmiconfig@9.0.0: resolution: {integrity: sha512-itvL5h8RETACmOTFc4UfIyB2RfEHi71Ax6E/PivVxq9NseKbOWpeyHEOIbmAw1rs8Ak0VursQNww7lf7YtUwzg==} engines: {node: '>=14'} @@ -792,6 +800,15 @@ packages: supports-color: optional: true + debug@4.4.0: + resolution: {integrity: sha512-6WTZ/IxCY/T6BALoZHaE4ctp9xm+Z5kY/pzYaCHRFeyVhojxlrm+46y68HA6hr0TcwEssoxNiDEUJQjfPZ/RYA==} + engines: {node: '>=6.0'} + peerDependencies: + supports-color: '*' + peerDependenciesMeta: + supports-color: + optional: true + decompress-response@6.0.0: resolution: {integrity: sha512-aW35yZM6Bb/4oJlZncMH2LCoZtJXTRxES17vE3hoRiowU2kWHaJKFkSBDnDR+cm9J+9QhXmREyIfv0pji9ejCQ==} engines: {node: '>=10'} @@ -1222,6 +1239,10 @@ packages: resolution: {integrity: sha512-2yTgeWTWzMWkHu6Jp9NKgePDaYHbntiwvYuuJLbbN9vl7DC9DvXKOB2BC3ZZ92D3cvV/aflH0osDfwpHepQ53w==} hasBin: true + jiti@2.4.1: + resolution: {integrity: sha512-yPBThwecp1wS9DmoA4x4KR2h3QoslacnDR8ypuFM962kI4/456Iy1oHx2RAgh4jfZNdn0bctsdadceiBUgpU1g==} + hasBin: true + js-tokens@4.0.0: resolution: {integrity: sha512-RdJUflcE3cUzKiMqQgsCu06FPu9UdIJO0beYbPhHN4k6apgJtifcoCtT9bcxOpYBtpD2kCM6Sbzg4CausW/PKQ==} @@ -1267,20 +1288,20 @@ packages: resolution: {integrity: sha512-+bT2uH4E5LGE7h/n3evcS/sQlJXCpIp6ym8OWJ5eV6+67Dsql/LaaT7qJBAt2rzfoa/5QBGBhxDix1dMt2kQKQ==} engines: {node: '>= 0.8.0'} - lilconfig@3.1.2: - resolution: {integrity: sha512-eop+wDAvpItUys0FWkHIKeC9ybYrTGbU41U5K7+bttZZeohvnY7M9dZ5kB21GNWiFT2q1OoPTvncPCgSOVO5ow==} + lilconfig@3.1.3: + resolution: {integrity: sha512-/vlFKAoH5Cgt3Ie+JLhRbwOsCQePABiU3tJ1egGvyQ+33R/vcwM2Zl2QR/LzjsBeItPt3oSVXapn+m4nQDvpzw==} engines: {node: '>=14'} lines-and-columns@1.2.4: resolution: {integrity: sha512-7ylylesZQ/PV29jhEDl3Ufjo6ZX7gCqJr5F7PKrqc93v7fzSymt1BpwEU8nAUXs8qzzvqhbjhK5QZg6Mt/HkBg==} - lint-staged@15.2.10: - resolution: {integrity: sha512-5dY5t743e1byO19P9I4b3x8HJwalIznL5E1FWYnU6OWw33KxNBSLAc6Cy7F2PsFEO8FKnLwjwm5hx7aMF0jzZg==} + lint-staged@15.2.11: + resolution: {integrity: sha512-Ev6ivCTYRTGs9ychvpVw35m/bcNDuBN+mnTeObCL5h+boS5WzBEC6LHI4I9F/++sZm1m+J2LEiy0gxL/R9TBqQ==} engines: {node: '>=18.12.0'} hasBin: true - listr2@8.2.4: - resolution: {integrity: sha512-opevsywziHd3zHCVQGAj8zu+Z3yHNkkoYhWIGnq54RrCVwLz0MozotJEDnKsIBLvkfLGN6BLOyAeRrYI0pKA4g==} + listr2@8.2.5: + resolution: {integrity: sha512-iyAZCeyD+c1gPyE9qpFu8af0Y+MRtmKOncdGoA2S5EY8iFq99dmmvkNnHiWo+pj0s7yH7l3KPIgee77tKpXPWQ==} engines: {node: '>=18.0.0'} locate-path@5.0.0: @@ -1932,8 +1953,8 @@ packages: resolution: {integrity: sha512-r3vXyErRCYJ7wg28yvBY5VSoAF8ZvlcW9/BwUzEtUsjvX/DKs24dIkuwjtuprwJJHsbyUbLApepYTR1BN4uHrg==} engines: {node: '>= 6'} - yaml@2.5.1: - resolution: {integrity: sha512-bLQOjaX/ADgQ20isPJRvF0iRUHIxVhYvr53Of7wGcWlO2jvtUlH5m87DsmulFVxRpNLOnI4tB6p/oh8D7kpn9Q==} + yaml@2.6.1: + resolution: {integrity: sha512-7r0XPzioN/Q9kXBro/XPnA6kznR73DHq+GXh5ON7ZozRO6aMjbmiBuKste2wslTFkC5d1dw0GooOCepZXJ2SAg==} engines: {node: '>= 14'} hasBin: true @@ -2029,7 +2050,7 @@ snapshots: '@babel/helper-split-export-declaration': 7.24.7 '@babel/parser': 7.25.6 '@babel/types': 7.25.6 - debug: 4.3.7 + debug: 4.4.0 globals: 11.12.0 transitivePeerDependencies: - supports-color @@ -2202,11 +2223,11 @@ snapshots: human-id: 1.0.2 prettier: 2.8.8 - '@commitlint/cli@19.6.0(@types/node@20.16.9)(typescript@5.7.2)': + '@commitlint/cli@19.6.1(@types/node@20.16.9)(typescript@5.7.2)': dependencies: '@commitlint/format': 19.5.0 '@commitlint/lint': 19.6.0 - '@commitlint/load': 19.5.0(@types/node@20.16.9)(typescript@5.7.2) + '@commitlint/load': 19.6.1(@types/node@20.16.9)(typescript@5.7.2) '@commitlint/read': 19.5.0 '@commitlint/types': 19.5.0 tinyexec: 0.3.0 @@ -2253,7 +2274,7 @@ snapshots: '@commitlint/rules': 19.6.0 '@commitlint/types': 19.5.0 - '@commitlint/load@19.5.0(@types/node@20.16.9)(typescript@5.7.2)': + '@commitlint/load@19.6.1(@types/node@20.16.9)(typescript@5.7.2)': dependencies: '@commitlint/config-validator': 19.5.0 '@commitlint/execute-rule': 19.5.0 @@ -2261,7 +2282,7 @@ snapshots: '@commitlint/types': 19.5.0 chalk: 5.3.0 cosmiconfig: 9.0.0(typescript@5.7.2) - cosmiconfig-typescript-loader: 5.0.0(@types/node@20.16.9)(cosmiconfig@9.0.0(typescript@5.7.2))(typescript@5.7.2) + cosmiconfig-typescript-loader: 6.1.0(@types/node@20.16.9)(cosmiconfig@9.0.0(typescript@5.7.2))(typescript@5.7.2) lodash.isplainobject: 4.0.6 lodash.merge: 4.6.2 lodash.uniq: 4.5.0 @@ -2771,6 +2792,13 @@ snapshots: jiti: 1.21.6 typescript: 5.7.2 + cosmiconfig-typescript-loader@6.1.0(@types/node@20.16.9)(cosmiconfig@9.0.0(typescript@5.7.2))(typescript@5.7.2): + dependencies: + '@types/node': 20.16.9 + cosmiconfig: 9.0.0(typescript@5.7.2) + jiti: 2.4.1 + typescript: 5.7.2 + cosmiconfig@9.0.0(typescript@5.7.2): dependencies: env-paths: 2.2.1 @@ -2807,6 +2835,10 @@ snapshots: dependencies: ms: 2.1.3 + debug@4.4.0: + dependencies: + ms: 2.1.3 + decompress-response@6.0.0: dependencies: mimic-response: 3.1.0 @@ -2979,7 +3011,7 @@ snapshots: execa@8.0.1: dependencies: - cross-spawn: 7.0.3 + cross-spawn: 7.0.6 get-stream: 8.0.1 human-signals: 5.0.0 is-stream: 3.0.0 @@ -3250,6 +3282,8 @@ snapshots: jiti@1.21.6: {} + jiti@2.4.1: {} + js-tokens@4.0.0: {} js-yaml@3.14.1: @@ -3288,26 +3322,26 @@ snapshots: prelude-ls: 1.2.1 type-check: 0.4.0 - lilconfig@3.1.2: {} + lilconfig@3.1.3: {} lines-and-columns@1.2.4: {} - lint-staged@15.2.10: + lint-staged@15.2.11: dependencies: chalk: 5.3.0 commander: 12.1.0 - debug: 4.3.7 + debug: 4.4.0 execa: 8.0.1 - lilconfig: 3.1.2 - listr2: 8.2.4 + lilconfig: 3.1.3 + listr2: 8.2.5 micromatch: 4.0.8 pidtree: 0.6.0 string-argv: 0.3.2 - yaml: 2.5.1 + yaml: 2.6.1 transitivePeerDependencies: - supports-color - listr2@8.2.4: + listr2@8.2.5: dependencies: cli-truncate: 4.0.0 colorette: 2.0.20 @@ -3887,7 +3921,7 @@ snapshots: yaml@1.10.2: {} - yaml@2.5.1: {} + yaml@2.6.1: {} yargs-parser@21.1.1: {}