@@ -8,13 +8,14 @@ OpenAPI(2.0/3.0/3.1) Schema → Type-safe Axios
8
8
[ ![ 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 )
9
9
[ ![ npm version] ( https://badge.fury.io/js/openapi-axios.svg )] ( https://npmjs.com/package/openapi-axios )
10
10
11
- 将 OpenAPI 规范声明文件转换为类型声明和可执行函数(基于 Axios)。与其他同类工具相比,具有以下特点:
11
+ 将 OpenAPI 规范声明文件转换为类型安全的基于 Axios 的函数。
12
12
13
13
- 😆 同时支持 [ 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(待完成)
18
19
19
20
# 安装
20
21
@@ -38,104 +39,120 @@ const { defineConfig } = require('openapi-axios');
38
39
* @ref https://github.com/FrontEndDev-org/openapi-axios
39
40
*/
40
41
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'
43
44
},
44
45
});
45
46
```
46
47
47
- ## 生成 API 文件
48
+ ## 生成 OpenAPI 相关文件
48
49
``` shell
49
50
# 根据配置文件生成typescript文件
50
51
npx openapi-axios
51
52
52
- # 将会生成 src/apis/.petStore3.ts 文件
53
+ # 将会生成 src/apis/petStore3.ts 文件
54
+ # 将会生成 src/apis/petStore3.type.ts 文件
53
55
```
54
56
55
57
<details >
56
- <summary >【点击展开】生成的文件将导出为一个函数和一个操作,如下所示 </summary >
58
+ <summary >src/apis/petStore3.ts 【点击展开】</summary >
57
59
58
60
``` ts
59
61
/**
60
- * @title Swagger Petstore - OpenAPI 3.1
61
- * @version 1.0.6
62
+ * @title Swagger Petstore - OpenAPI 3.0
63
+ * @version 1.0.19
62
64
* @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)
68
73
*/
69
74
70
- import type { AxiosPromise , AxiosRequestConfig } from ' axios' ;
75
+ import type { AxiosRequestConfig , AxiosResponse } from ' axios' ;
76
+ import type * as Type from ' ./pet-store.type.ts' ;
71
77
import axios from ' axios' ;
72
78
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
+
73
96
// ... 省略 ...
97
+ ```
98
+ </details >
74
99
100
+ <details >
101
+ <summary >src/apis/petStore3.type.ts【点击展开】</summary >
102
+
103
+ ``` ts
75
104
/**
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)
77
116
*/
117
+
118
+ // ... 省略 ...
119
+
78
120
export interface Pet {
79
121
/**
80
122
* @format int64
81
123
* @example 10
82
124
*/
83
125
id? : number ;
84
- /**
85
- * @description Pet Category
86
- */
87
- category? : Category ;
88
126
/**
89
127
* @example doggie
90
128
*/
91
129
name: string ;
92
- photoUrls: string ;
93
- tags? : Tag ;
130
+ category? : Category ;
131
+ photoUrls: Array <string >;
132
+ tags? : Array <Tag >;
94
133
/**
95
134
* @description pet status in the store
96
135
*/
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' );
105
137
}
106
138
107
139
// ... 省略 ...
108
140
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 ;
125
143
126
144
// ... 省略 ...
127
145
```
128
146
</details >
129
147
130
- 然后你可以直接导入一个函数并使用它。 调用接口就像调用本地函数一样简单。
148
+ 然后你可以直接导入一个函数来使用它:
131
149
132
150
``` ts
133
- import { updatePet } from ' @/apis/.petStore3' ;
151
+ import { addPet } from ' @/apis/.petStore3' ;
134
152
135
153
// 类型安全
136
- const { data : pet } = await updatePet ({
154
+ const { data : pet } = await addPet ({
137
155
name: ' MyCat' ,
138
- photoUrls: [' photo1' , ' photo2' ]
139
156
});
140
157
141
158
// 类型安全
0 commit comments