Skip to content

openapi-axios 0.16.0

Install from the command line:
Learn more about npm packages
$ npm install @frontenddev-org/openapi-axios@0.16.0
Install via package.json:
"@frontenddev-org/openapi-axios": "0.16.0"

About this version

openapi-axios

OpenAPI ➡️ Axios

code-review dependency-review Codacy Badge Codacy Badge npm version

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

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

安装

npm i -D openapi-axios
yarn add --dev openapi-axios

使用

命令行

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

// openapi.config.cjs
const { defineConfig } = require('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',
    },
  ],
});
【点击展开】url在swagger页面标题的下方，如下图所示：

swagger-url-position.png

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

# 将会生成 src/apis/swagger/petStore3.ts 文件
【点击展开】生成的文件将导出为一个函数和一个操作，如下所示 
// src/apis/swagger/petStore3.ts

import type { OneOf } from 'openapi-axios/helpers';
import type { AxiosPromise, AxiosRequestConfig } from 'axios';
import {
  DELETE,
  GET,
  HEAD,
  OPTIONS,
  PATCH,
  POST,
  PUT,
  resolveURL,
} from 'openapi-axios/helpers';
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

参数名 类型 可选性 描述 默认值
cwd string false 当前工作路径 process.cwd()
dest string false 目标目录 src/apis
parser ParserOptions false 解析配置 undefined
printer PrinterOptions false 输出配置 undefined
openAPIs OpenAPIOptions[] true OpenAPIOptions 列表，至少需要配置一个 无

ParserOptions 签名：

参数名 类型 可选性 描述 默认值
cwd string false 当前工作路径 process.cwd()
okCode number false ok 的响应码 200
okMediaType number false ok 的响应类型 application/json
nameFormatter function false 自定义name格式化方法，函数签名 (props: NameFormatterProps) => string; ({name}) => name
requestPathTypeName string false 请求路径参数类型名称 ReqPath
requestQueryTypeName string false 请求查询参数类型名称 ReqParams
requestBodyTypeName string false 请求体参数类型名称 ReqData
responseBodyTypeName string false 响应体参数类型名称 ResData
【点击展开】查看 NameFormatterProps 签名

NameFormatterProps 签名：

参数名 类型 可选性 描述 默认值
name string true 原始名称（经过内部处理，能保证唯一） 无
method string true 方法 无
path string true 路径 无
operationId string false operationId 无

PrinterOptions 签名：

参数名 类型 可选性 描述 默认值
axiosImport string false axios 导入内容 默认从官方 Axios 导入，可以使用自己实现的客户端
prettier object false prettier 配置 { singleQuote: true }
requestPathArgName string false 请求路径参数入参名称 path
requestQueryArgName string false 请求查询参数入参名称 params
requestBodyArgName string false 请求体参数入参名称 data
responseTypeName string false 响应类型名称 AxiosPromise

OpenAPIOptions 签名:

名称 类型 可选 描述 默认值
name string 必须 openapi 的名称，将会生成 ${name}.ts 文件 undefined
document string,OpenAPI3Document 必须 openapi 文档，可以是一个 URL 链接或者本地路径，或者一个 OPENAPI3 文档对象 undefined

Details

Assets

  • openapi-axios-0.16.0.tgz

Download activity

  • Total downloads 0
  • Last 30 days 0
  • Last week 0
  • Today 0

Recent versions

View all