@happygen/openapi-axios v0.1.5

openapi-axios

OpenAPI ➡️ Axios

将 OpenAPI 规范声明文件转换为类型声明和可执行函数（基于 Axios）。与其他同类工具相比，具有以下特点：

• 😆 支持 openAPI v3（当前仅）
• 😉 每个 API 都是一个函数，用于在构建时轻松进行 tree shaking
• 😎 与最流行的 HTTP 客户端 axios 进行适配
• 🤗 轻松与本地请求客户端集成，例如在本地项目中创建的 Axios 实例（通常我们在本地都是需要自定义一些拦截器什么的）
• 😁 易于使用，易于学习，类型安全

安装

npm i -D @happygen/openapi-axios
yarn add --dev @happygen/openapi-axios
pnpm i -D @happygen/openapi-axios

使用

命令行

在项目根目录下创建配置文件，配置文件的搜索顺序是 openapi.config.cjs、openapi.config.js。

// openapi.config.cjs
const { defineConfig } = require('@happygen/openapi-axios');

module.exports = defineConfig({
  openAPIs: [
    {
      // 将会生成 src/apis/swagger/petStore3.ts 文件
      name: 'swagger/petStore3',
      // 可以是一个 URL 链接或者本地路径，或者一个 OPENAPI3 文档对象
      document: 'https://petstore3.swagger.io/api/v3/openapi.json',
    },
  ],
});

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

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

// src/apis/swagger/petStore3.ts

import type { OneOf } from '@happygen/openapi-axios/helpers';
import type { AxiosPromise, AxiosRequestConfig } from 'axios';
import {
  DELETE,
  GET,
  HEAD,
  OPTIONS,
  PATCH,
  POST,
  PUT,
  resolveURL,
} from '@happygen/openapi-axioshelpers';
import axios from 'axios';

const request = axios.request;
const BASE_URL = '/api/v3';

// ...

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

// ...

export type AddPetReqData = Pet;
export type AddPetResData = Pet;
/**
 * @title Add a new pet to the store
 * @description Add a new pet to the store
 */
export async function addPet(
  data: AddPetReqData,
  config?: AxiosRequestConfig
): AxiosPromise<AddPetResData> {
  return request({
    url: resolveURL(BASE_URL, `/pet`),
    method: POST,
    data,
    ...config,
  });
}

// ...

然后你可以直接导入一个函数并使用它。 调用接口就像调用本地函数一样简单，是不是类似于 RPC（remote procedure call）。

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

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

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

openapi.config

ParserOptions 签名：

NameFormatterProps 签名：

PrinterOptions 签名：

OpenAPIOptions 签名: