OpenAPI(2.0/3.0/3.1) Schema → Type-safe Axios
npm install openapi-axiosOpenAPI(2.0/3.0/3.1) Schema → Type-safe Axios
将 OpenAPI 规范声明文件转换为类型安全的基于 Axios 的函数。
- 😆 同时支持 openAPI 2.0、3.0、3.1 规范
- 😎 与最流行的 HTTP 客户端 axios 进行适配
- 😉 类型安全的请求函数，轻松进行 tree shaking
- 🤔 基于 zod 支持了接口出入参的校验（可选）
- 😋 支持生成原 Schema 文件以及中间处理的 Schema 文件（可选）
- 🤗 支持接口 Mock（可选）
``shell`
npm i -D openapi-axios@latest
npm i axios
shell
npx openapi-axios init
`
将在项目根目录下创建配置文件 openapi.config.cjs：
js
const { defineConfig } = require('openapi-axios');/**
* openapi-axios config
* @ref https://github.com/FrontEndDev-org/openapi-axios
*/
module.exports = defineConfig({
documents: {
petStore3: 'https://petstore3.swagger.io/api/v3/openapi.json'
},
});
`生成 OpenAPI 相关文件
shell
根据配置文件生成typescript文件
npx openapi-axios将会生成 src/apis/petStore3.ts 文件
将会生成 src/apis/petStore3.type.ts 文件
`
src/apis/petStore3.ts【点击展开】
ts
/**
* @title Swagger Petstore - OpenAPI 3.0
* @version 1.0.19
* @contact
* @description This is a sample Pet Store Server based on the OpenAPI 3.0 specification. You can find out more about
* Swagger at http://swagger.io. In the third iteration of the pet store, we've switched to the design first approach!
* You can now help us improve the API whether it's by making changes to the definition itself or to the code.
* That way, with time, we can improve the API in general, and expose some of the new features in OAS3.
*
* Some useful links:
* - The Pet Store repository
* - The source API definition for the Pet Store
*/import type * as Type from './pet-store.type.ts';
import axios from 'axios';
type AxiosRequestConfig = Parameters[0];
/**
* @description Add a new pet to the store
* @summary Add a new pet to the store
* @see pet Everything about your Pets {@link http://swagger.io Find out more}
* @param data Create a new pet in the store
* @param [config] request config
* @returns Successful operation
*/
export async function addPet(data: Type.AddPetData, config?: AxiosRequestConfig): Promise> {
return axios({
method: 'POST',
url:
/pet,
data,
...config
});
}// ... 省略 ...
`
src/apis/petStore3.type.ts【点击展开】
ts
/**
* @title Swagger Petstore - OpenAPI 3.0
* @version 1.0.19
* @contact
* @description This is a sample Pet Store Server based on the OpenAPI 3.0 specification. You can find out more about
* Swagger at http://swagger.io. In the third iteration of the pet store, we've switched to the design first approach!
* You can now help us improve the API whether it's by making changes to the definition itself or to the code.
* That way, with time, we can improve the API in general, and expose some of the new features in OAS3.
*
* Some useful links:
* - The Pet Store repository
* - The source API definition for the Pet Store
*/// ... 省略 ...
export interface Pet {
/**
* @format int64
* @example 10
*/
id?: number;
/**
* @example doggie
*/
name: string;
category?: Category;
photoUrls: Array;
tags?: Array;
/**
* @description pet status in the store
*/
status?: ('available' | 'pending' | 'sold');
}
// ... 省略 ...
export type AddPetData = Pet;
export type AddPetResponse = Pet;
// ... 省略 ...
`
然后你可以直接导入一个函数来使用它：
ts
import { addPet } from '@/apis/.petStore3';// 类型安全
const { data: pet } = await addPet({
name: 'MyCat',
});
// 类型安全
console.log(pet);
``