快速将 Swagger 数据转换为 请求代码 和 类型定义。
主要包含两部分功能：
- 自动生成类型完备的请求代码；
- 自动生成并导出生成的
interfaceenum；
apiFetch 方法。
- 自动化：只需一次设置，就可以自动将后端的
Swagger文档转换为TypeScript文件。 - 准确性：通过直接从
Swagger文档生成类型定义，极大减少前后端程序员的沟通成本。 - 高效率：自动生成请求代码和类型定义，极大提高了开发效率。
- 可维护：自动生成的
interfaceenum默认导出，可以在业务代码直接使用，极大的提高了代码的可维护性。 - 无侵入：无预设请求框架，仅生成请求方法调用，与手写代码保持完全一致。
- 自定义：
extraOptions可以满足你的自定义需求，这个参数工具内不会使用，仅透传至调用的请求方法。
npm install api-gear -D// file: api-gear.config.js
const path = require("path");
module.exports = () => {
return [
{
output: path.resolve(__dirname, "./autoApi"),
// 直接放链接地址
source: "your api path", // XXX/swagger/doc.json (json)
// // 对象配置方法
// source: {
// url: "your api path",
// },
// // 直接放swagger数据
// source: {
// data: {
// "paths": {
// "/v1/attachment": {
// "post": {
// "summary": "创建 Attachment",
// "deprecated": false,
// "description": "创建 Attachment",
// }
// }
// }
// // ...
// }
// },
// // 直接放函数
// source: {
// data: async () => {
// return {
// "paths": {
// "/v1/attachment": {
// "post": {
// "summary": "创建 Attachment",
// "deprecated": false,
// "description": "创建 Attachment",
// }
// }
// }
// }
// }
// }
// if you need auth
auth: {
username: "xxx",
password: "xx",
},
// if you want add somme custom the tag
tagsCreator: () => {
return [
{
tagName: 'demo',
text: 'your text',
}
]
}
}
];
};import axios from "axios";
export const apiFetch = <T = any>(options: {url: string, method: "GET" | "POST" | "PUT" | "DELETE", path?: Record<string, string>, params?: Record<string, any>, data?: Record<string, any>}, extraOptions?: any ) => {
let { path = {}, url = "", method, params, data} = options;
Object.keys(path).forEach((key) => {
url = url?.replace(new RegExp(`{${key}}`, 'g'), path[key] ?? '');
});
return axios<T>({
url,
method,
params,
data
})
}{
"scripts": {
"api": "api-gear"
}
}npm run api// file: src/autoApi/api/v1/product/index.ts
import { apiFetch } from "@/common/utils/axios";
import { Rest_Response_Dto_PaginationResponse_Ent_Products, Ent_Products, Rest_Response_Ent_Products } from "../../types";
/**
* 获取 Product 列表
* @author
* @desc 获取 Product 列表
* @link https://xxxx/swagger/index.html#/product/get_api_v1_product
* @host https://xxx
*/
export function GET(options: { params: { page_num?: number, page_size?: number, field?: string, op?: string, value?: string } }, extraOptions?: any) {
return apiFetch<Rest_Response_Dto_PaginationResponse_Ent_Products>({
url: "/api/v1/product",
method: "GET",
...options,
}, extraOptions)
}
/**
* 创建 Product
* @author
* @desc 创建 Product
* @link https://xxx/swagger/index.html#/product/post_api_v1_product
* @host https://xxx
*/
export function POST(options: { data: { product: Ent_Products } }, extraOptions?: any) {
return apiFetch<Rest_Response_Ent_Products>({
url: "/api/v1/product",
method: "POST",
...options,
}, extraOptions)
}
// file: src/autoApi/types.ts
export interface Rest_Response_Dto_PaginationResponse_Ent_Products {
/** xx */
code?: number;
/** xx */
data?: Dto_PaginationResponse_Ent_Products;
/** xx */
message?: string;
/** xx */
trace_id?: string;
}
export enum Users_Source {
SourceTEAM = "TEAM",
SourceSINGPASS = "SINGPASS",
SourceINTERNAL = "INTERNAL"
}
// ...more| 选项名称 | 描述 | 类型 | 默认值 |
|---|---|---|---|
| output | 文件生成目录(完整路径) | string | path.join(process.cwd(), "./api-gear") |
| interfaceFileName | 类型定义文件名称 | string | types.ts |
| fetchMethodPath | 请求方法路径地址 | string | @/common/utils/axios |
| fetchMethodName | 请求方法名称 | string | apiFetch |
| source | 数据源 | ServiceMapItem | null |
| newLineKind | 行尾序列 | 'CRLF'|'LF' | 'LF'( --nlk=CRLF 修改) |
| sort | 生成interface时，对成员名称排序(数据内容key顺序不稳定，开启可以防止无效的文件变更) | boolean | false (--sort=true 修改) |
| pathFilter | 过滤目标项（用于更新单个接口） | (path: string) => boolean | () => true |
| auth | Bear Auth | Auth | undefined |
| tagsCreator | 自定义tags | (arg: { data: any; route: string; apiPath: string; methodType: string; methodMetaData: any }) => { tagName: string; text: string }[]; | () => [] |
| urlCreator | 自定义url路径（当你需要proxy配置时特别有用） | urlCreator: (arg: { data: any; route: string; apiPath: string; methodType: string; methodMetaData: any }) => string; | ({apiPath}) => apiPath |
| beforeSaveHook | 在生成的文件保存前调用，可以用于调整文件内容 | (arg: { sourceFile: SourceFile; route: string; data: any; mode: string }) => Promise | async () => {} |
export type Auth = {
username: string;
password: string;
}
export type ServiceMapItem = string | {
url?: string,
// 如果提供数据，则会优先使用提供的swagger数据进行转换, 如果是函数，则会在运行时调用，将返回的数据用于接口转换
data?:() => Promise<any> | any,
// 当前service发起数据请求时auth的优先顺序为 局部 auth => 全局 auth,
auth?: Auth;
}欢迎大家提 issue, 但希望你能提供你的配置，或者给出类型转换有异常的swagger json 数据，描述清楚如何复现问题。我将不定期清理issue。希望你使用愉快。