api-gear

快速将 Swagger 数据转换为 请求代码 和 类型定义。

‼️重要：如果这个项目对你有帮助，请给项目点个Star支持一下吧😊！

内容列表

• api-gear
  • 内容列表
  • 适用场景
  • 主要特性
  • 快速开始
    • 安装
    • 在项目根目录添加配置文件
    • 编写apiFetch方法
    • 在项目内的package.json中配置命令
    • 运行命令， 生成接口类型定义
  • 生成示例
  • 配置说明
  • 类型
  • Star History
  • License
  • 写在最后

适用场景

主要包含两部分功能：

1. 自动生成类型完备的请求代码；
2. 自动生成并导出生成的 interface enum；

⚠️ 功能非常简单，没有魔法🪄，只做转换功能，没有内置的请求实现，所以需要自行在项目中实现 apiFetch 方法。

主要特性

1. 自动化：只需一次设置，就可以自动将后端的 Swagger 文档转换为 TypeScript 文件。
2. 准确性：通过直接从 Swagger 文档生成类型定义，极大减少前后端程序员的沟通成本。
3. 高效率：自动生成请求代码和类型定义，极大提高了开发效率。
4. 可维护：自动生成的interface enum 默认导出，可以在业务代码直接使用，极大的提高了代码的可维护性。
5. 无侵入：无预设请求框架，仅生成请求方法调用，与手写代码保持完全一致。
6. 自定义：extraOptions 可以满足你的自定义需求，这个参数工具内不会使用，仅透传至调用的请求方法。
7. 多服务：可以同时配置多个代码转换服务且相互独立，对有多个后端服务需要进行API转换的情况也能简单适配。

快速开始

安装

1npm install api-gear -D

在项目根目录添加配置文件

1// file: api-gear.config.ts
2import path from 'path';
3import { defineConfig } from "api-gear";
4
5// 注意此处为 async 函数
6export default defineConfig(async() => {
7    // 可以配置多个
8    return [
9        {
10            output: path.resolve(__dirname, "./autoApi"),
11            // 直接放链接地址（注意是http或https协议的资源地址）
12            source: "your api path", // http://XXX/swagger/doc.json (json)
13            // // 对象配置方法
14            // source: {
15            //     url: "your api path",
16            // // if you need auth
17            //     auth: {
18            //         username: "xxx",
19            //         password: "xx",
20            //     },
21            // },
22            // // 直接放swagger数据
23            // source: {
24            //     data: {
25            //         "paths": {
26            //             "/v1/attachment": {
27            //                 "post": {
28            //                     "summary": "创建 Attachment",
29            //                     "deprecated": false,
30            //                     "description": "创建 Attachment",
31            //                 }
32            //             }
33            //         }
34            //         // ...
35            //     }
36            // },
37            // // 直接放函数
38            // source: {
39            //     data: async () => {
40            //         return {
41            //             "paths": {
42            //                 "/v1/attachment": {
43            //                     "post": {
44            //                         "summary": "创建 Attachment",
45            //                         "deprecated": false,
46            //                         "description": "创建 Attachment",
47            //                     }
48            //                 }
49            //             }
50            //         }
51            //     }
52            // }           
53            // if you want add somme custom the tag
54            tagsCreator: () => {
55                return [
56                    {
57                        tagName: 'demo',
58                        text: 'your text',
59                    }
60                ]
61            }
62        }
63    ];
64});

编写apiFetch方法

1import axios from "axios";
2
3export 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 ) => {
4    let { path = {}, url = "", method, params, data} = options;
5    Object.keys(path).forEach((key) => {
6        url = url?.replace(new RegExp(`{${key}}`, 'g'), path[key] ?? '');
7    });
8    return axios<T>({
9        url,
10        method,
11        params,
12        data
13    })
14}

在项目内的package.json中配置命令

1{
2  "scripts": {
3    "api": "api-gear"
4  }
5}

运行命令， 生成接口类型定义

1npm run api

生成示例

1// file:  src/autoApi/api/v1/product/index.ts
2import { apiFetch } from "@/common/utils/axios";
3import { Rest_Response_Dto_PaginationResponse_Ent_Products, Ent_Products, Rest_Response_Ent_Products } from "../../types";
4
5/**
6 * 获取 Product 列表
7 * @author
8 * @desc 获取 Product 列表
9 * @link https://xxxx/swagger/index.html#/product/get_api_v1_product
10 * @host https://xxx
11 */
12export function GET(options: { params: { page_num?: number, page_size?: number, field?: string, op?: string, value?: string } }, extraOptions?: any) {
13    return apiFetch<Rest_Response_Dto_PaginationResponse_Ent_Products>({
14        url: "/api/v1/product",
15        method: "GET",
16        ...options,
17    }, extraOptions)
18}
19
20/**
21 * 创建 Product
22 * @author
23 * @desc 创建 Product
24 * @link https://xxx/swagger/index.html#/product/post_api_v1_product
25 * @host https://xxx
26 */
27export function POST(options: { data: { product: Ent_Products } }, extraOptions?: any) {
28    return apiFetch<Rest_Response_Ent_Products>({
29        url: "/api/v1/product",
30        method: "POST",
31        ...options,
32    }, extraOptions)
33}
34
35
36

1// file: src/autoApi/types.ts
2export interface Rest_Response_Dto_PaginationResponse_Ent_Products {
3    /** xx */
4    code?: number;
5    /** xx */
6    data?: Dto_PaginationResponse_Ent_Products;
7    /** xx */
8    message?: string;
9    /** xx */
10    trace_id?: string;
11}
12
13export enum Users_Source {
14    SourceTEAM = "TEAM",
15    SourceSINGPASS = "SINGPASS",
16    SourceINTERNAL = "INTERNAL"
17}
18
19// ...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
source.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
transformDataHook	在获取的swagger数据用于代码生成前调用，可以用于元数据调整	transformDataHook: (data: any) => Promise;	(data) => data,
beforeSaveHook	在生成的文件保存前调用，可以用于调整文件内容	(arg: { sourceFile: SourceFile; route: string; data: any; mode: string }) => Promise	async () => {}

类型

1
2export type Auth = {
3    username: string;
4    password: string;
5}
6
7export type ServiceMapItem = string | {
8    url?: string,
9    // 如果提供数据，则会优先使用提供的swagger数据进行转换, 如果是函数，则会在运行时调用，将返回的数据用于接口转换
10    data?:() => Promise<any> | any,
11    // 当前service发起数据请求时auth的优先顺序为 局部 auth => 全局 auth,
12    auth?: Auth;
13}

Star History

License

MIT

写在最后

欢迎大家提 issue, 但希望你能提供你的配置，或者给出类型转换有异常的swagger json 数据，描述清楚如何复现问题。我将不定期清理issue。希望你使用愉快。