openapi-axios

OpenAPI(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（可选）

安装

npm i -D openapi-axios@latest
npm i axios

使用

创建配置文件

npx openapi-axios init

将在项目根目录下创建配置文件 openapi.config.cjs：

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 相关文件

# 根据配置文件生成typescript文件
npx openapi-axios

# 将会生成 src/apis/petStore3.ts 文件
# 将会生成 src/apis/petStore3.type.ts 文件

src/apis/petStore3.ts【点击展开】

/**
 * @title Swagger Petstore - OpenAPI 3.0
 * @version 1.0.19
 * @contact <apiteam@swagger.io>
 * @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](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](https://github.com/swagger-api/swagger-petstore)
 * - [The source API definition for the Pet Store](https://github.com/swagger-api/swagger-petstore/blob/master/src/main/resources/openapi.yaml)
 */

import type * as Type from './pet-store.type.ts';
import axios from 'axios';

type AxiosRequestConfig = Parameters<typeof axios.request>[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<AxiosResponse<Type.AddPetResponse>> {
  return axios({
    method: 'POST',
    url: `/pet`,
    data,
    ...config
  });
}

// ... 省略 ...

src/apis/petStore3.type.ts【点击展开】

/**
 * @title Swagger Petstore - OpenAPI 3.0
 * @version 1.0.19
 * @contact <apiteam@swagger.io>
 * @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](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](https://github.com/swagger-api/swagger-petstore)
 * - [The source API definition for the Pet Store](https://github.com/swagger-api/swagger-petstore/blob/master/src/main/resources/openapi.yaml)
 */

// ... 省略 ...

export interface Pet {
  /**
   * @format int64
   * @example 10
   */
  id?: number;
  /**
   * @example doggie
   */
  name: string;
  category?: Category;
  photoUrls: Array<string>;
  tags?: Array<Tag>;
  /**
   * @description pet status in the store
   */
  status?: ('available' | 'pending' | 'sold');
}

// ... 省略 ...

export type AddPetData = Pet;
export type AddPetResponse = Pet;

// ... 省略 ...

然后你可以直接导入一个函数来使用它：

import { addPet } from '@/apis/.petStore3';

// 类型安全
const { data: pet } = await addPet({
  name: 'MyCat',
});

// 类型安全
console.log(pet);