Skip to content

Commit 5075c88

Browse files
committed
docs(README): 更新文档以反映新功能和代码结构
-描述了将 OpenAPI 规范声明文件转换为类型安全的基于 Axios 的函数 - 添加了对 zod 的支持用于接口出入参校验 - 增加了生成原 Schema 文件和中间处理的 Schema 文件的功能 - 提到了即将完成的接口 Mock 功能- 更新了示例代码和文件结构说明
1 parent f964fa1 commit 5075c88

File tree

1 file changed

+70
-53
lines changed

1 file changed

+70
-53
lines changed

README.md

Lines changed: 70 additions & 53 deletions
Original file line numberDiff line numberDiff line change
@@ -8,13 +8,14 @@ OpenAPI(2.0/3.0/3.1) Schema → Type-safe Axios
88
[![Codacy Badge](https://app.codacy.com/project/badge/Coverage/4fa1acaeb717469caddfe21a84c50bb2)](https://app.codacy.com/gh/FrontEndDev-org/openapi-axios/dashboard?utm_source=gh&utm_medium=referral&utm_content=&utm_campaign=Badge_coverage)
99
[![npm version](https://badge.fury.io/js/openapi-axios.svg)](https://npmjs.com/package/openapi-axios)
1010

11-
将 OpenAPI 规范声明文件转换为类型声明和可执行函数(基于 Axios)。与其他同类工具相比,具有以下特点:
11+
将 OpenAPI 规范声明文件转换为类型安全的基于 Axios 的函数。
1212

1313
- 😆 同时支持 [openAPI](https://www.openapis.org/) 2.0、3.0、3.1 规范
14-
- 😉 生成的每个 API 都是一个函数,用于在构建时轻松进行 tree shaking
15-
- 😎 与最流行的 HTTP 客户端 [axios](https://axios-http.com/) 进行适配
16-
- 🤗 轻松与本地请求客户端集成,例如在本地项目中创建的 Axios 实例(通常我们在本地都是需要自定义一些拦截器什么的)
17-
- 😁 易于使用,易于学习,类型安全
14+
- 😎 与最流行的 HTTP 客户端 [axios](https://axios-http.com/) 进行适配,可轻松与本地 Axios 实例集成
15+
- 😉 生成的每个 API 都是一个类型安全的函数,用于在构建时轻松进行 tree shaking
16+
- 🤔 基于 [zod](https://zod.dev/) 支持了接口出入参的校验(可选)
17+
- 😋 支持生成原 Schema 文件以及中间处理的 Schema 文件(可选)
18+
- 🤗 支持接口 Mock(待完成)
1819

1920
# 安装
2021

@@ -38,104 +39,120 @@ const { defineConfig } = require('openapi-axios');
3839
* @ref https://github.com/FrontEndDev-org/openapi-axios
3940
*/
4041
module.exports = defineConfig({
41-
modules: {
42-
'.petStore3': 'https://petstore3.swagger.io/api/v3/openapi.json'
42+
documents: {
43+
petStore3: 'https://petstore3.swagger.io/api/v3/openapi.json'
4344
},
4445
});
4546
```
4647

47-
## 生成 API 文件
48+
## 生成 OpenAPI 相关文件
4849
```shell
4950
# 根据配置文件生成typescript文件
5051
npx openapi-axios
5152

52-
# 将会生成 src/apis/.petStore3.ts 文件
53+
# 将会生成 src/apis/petStore3.ts 文件
54+
# 将会生成 src/apis/petStore3.type.ts 文件
5355
```
5456

5557
<details>
56-
<summary>【点击展开】生成的文件将导出为一个函数和一个操作,如下所示</summary>
58+
<summary>src/apis/petStore3.ts【点击展开】</summary>
5759

5860
```ts
5961
/**
60-
* @title Swagger Petstore - OpenAPI 3.1
61-
* @version 1.0.6
62+
* @title Swagger Petstore - OpenAPI 3.0
63+
* @version 1.0.19
6264
* @contact <apiteam@swagger.io>
63-
* @description This is a sample Pet Store Server based on the OpenAPI 3.1 specification.
64-
You can find out more about
65-
Swagger at [http://swagger.io](http://swagger.io).
66-
* @summary Pet Store 3.1
67-
* @see {@link http://swagger.io Find out more about Swagger}
65+
* @description This is a sample Pet Store Server based on the OpenAPI 3.0 specification. You can find out more about
66+
* Swagger at [http://swagger.io](http://swagger.io). In the third iteration of the pet store, we've switched to the design first approach!
67+
* You can now help us improve the API whether it's by making changes to the definition itself or to the code.
68+
* That way, with time, we can improve the API in general, and expose some of the new features in OAS3.
69+
*
70+
* Some useful links:
71+
* - [The Pet Store repository](https://github.com/swagger-api/swagger-petstore)
72+
* - [The source API definition for the Pet Store](https://github.com/swagger-api/swagger-petstore/blob/master/src/main/resources/openapi.yaml)
6873
*/
6974

70-
import type { AxiosPromise, AxiosRequestConfig } from 'axios';
75+
import type { AxiosRequestConfig, AxiosResponse } from 'axios';
76+
import type * as Type from './pet-store.type.ts';
7177
import axios from 'axios';
7278

79+
/**
80+
* @description Add a new pet to the store
81+
* @summary Add a new pet to the store
82+
* @see pet Everything about your Pets {@link http://swagger.io Find out more}
83+
* @param data Create a new pet in the store
84+
* @param [config] request config
85+
* @returns Successful operation
86+
*/
87+
export async function addPet(data: Type.AddPetData, config?: AxiosRequestConfig): Promise<AxiosResponse<Type.AddPetResponse>> {
88+
return axios({
89+
method: 'POST',
90+
url: `/pet`,
91+
data,
92+
...config
93+
});
94+
}
95+
7396
// ... 省略 ...
97+
```
98+
</details>
7499

100+
<details>
101+
<summary>src/apis/petStore3.type.ts【点击展开】</summary>
102+
103+
```ts
75104
/**
76-
* @description Pet
105+
* @title Swagger Petstore - OpenAPI 3.0
106+
* @version 1.0.19
107+
* @contact <apiteam@swagger.io>
108+
* @description This is a sample Pet Store Server based on the OpenAPI 3.0 specification. You can find out more about
109+
* Swagger at [http://swagger.io](http://swagger.io). In the third iteration of the pet store, we've switched to the design first approach!
110+
* You can now help us improve the API whether it's by making changes to the definition itself or to the code.
111+
* That way, with time, we can improve the API in general, and expose some of the new features in OAS3.
112+
*
113+
* Some useful links:
114+
* - [The Pet Store repository](https://github.com/swagger-api/swagger-petstore)
115+
* - [The source API definition for the Pet Store](https://github.com/swagger-api/swagger-petstore/blob/master/src/main/resources/openapi.yaml)
77116
*/
117+
118+
// ... 省略 ...
119+
78120
export interface Pet {
79121
/**
80122
* @format int64
81123
* @example 10
82124
*/
83125
id?: number;
84-
/**
85-
* @description Pet Category
86-
*/
87-
category?: Category;
88126
/**
89127
* @example doggie
90128
*/
91129
name: string;
92-
photoUrls: string;
93-
tags?: Tag;
130+
category?: Category;
131+
photoUrls: Array<string>;
132+
tags?: Array<Tag>;
94133
/**
95134
* @description pet status in the store
96135
*/
97-
status?: 'available' | 'pending' | 'sold';
98-
/**
99-
* @format int32
100-
* @example 7
101-
*/
102-
availableInstances?: number;
103-
petDetailsId?: unknown;
104-
petDetails?: unknown;
136+
status?: ('available' | 'pending' | 'sold');
105137
}
106138

107139
// ... 省略 ...
108140

109-
/**
110-
* @description Update an existing pet by Id
111-
* @summary Update an existing pet
112-
* @see pet Everything about your Pets {@link http://swagger.io Find out more}
113-
* @param data Pet object that needs to be updated in the store
114-
* @param [config] request config
115-
* @returns Successful operation
116-
*/
117-
export async function updatePet(data: Pet, config?: AxiosRequestConfig): AxiosPromise<Pet> {
118-
return axios({
119-
method: 'put',
120-
url: `/pet`,
121-
data,
122-
...config,
123-
});
124-
}
141+
export type AddPetData = Pet;
142+
export type AddPetResponse = Pet;
125143

126144
// ... 省略 ...
127145
```
128146
</details>
129147

130-
然后你可以直接导入一个函数并使用它。 调用接口就像调用本地函数一样简单。
148+
然后你可以直接导入一个函数来使用它:
131149

132150
```ts
133-
import { updatePet } from '@/apis/.petStore3';
151+
import { addPet } from '@/apis/.petStore3';
134152

135153
// 类型安全
136-
const { data: pet } = await updatePet({
154+
const { data: pet } = await addPet({
137155
name: 'MyCat',
138-
photoUrls: ['photo1', 'photo2']
139156
});
140157

141158
// 类型安全

0 commit comments

Comments
 (0)