swagger-api-helper

install

npm install swagger-api-helper --save-dev

mock

根据 swagger json 数据 生成 mock 数据

express

const { mock } = require('swagger-api-helper');
const app = express();
const urls = ['https://petstore.swagger.io/v2/swagger.json'];
mock(app, {
    basePath: '/api',
    // 是否允许所有跨域 默认 false
    cors: false,
    urls,
    fetchOptions: {
        headers: {
            Authorization: 'Basic YWRtaW46dENmcWU4JEph',
        },
    },
});

webpack

const { mock } = require('swagger-api-helper');
devServer: {
    before: app => {
        mock(app, {
            basePath: '/api',
            urls,
            // 是否允许所有跨域 默认 false
            cors: false,
        });
    },
},

mock options

| 字段 | 类型 | 必填 | 描述 | | ---------------- | ----------------------------------------------------------------------------------- | ---- | -------------------------------------------------------------------------------------------------------------------- | | enableWatcher | boolean | 否 | 是否开启监听 api 目录, 开启后将监听目录, 目录变化时重新请求 swagger 数据 | | urls | string[] | [string, string, { headers, query, method, body }][] | 是 | 单个 url 为数组时，第二个属性为需要监听的目录路径, 当目录中文件变化时，重新生成定义 mock 数据, 第三个属性为 请求属性 | | fetchOptions | { headers, query, method, body } | 否 | swagger 请求 属性 包括 header, body, method, query | | propertyResolver | (dataKey: string, type: Type, Mock: Mockjs) => any | 否 | 处理单个请求 response 中的单个属性的 mock 结果 | | resultResolver | (payload: { url: string; method: Methods; path: string; swaggerPath: Path }) => any | 否 | 处理单个请求 response 的 mock 结果 | | basePath | string | 否 | 请求 mock api 时的接口前缀 | | cors | boolean | 否 | 默认 false, 是否开启跨域 |

generate

根据 swagger json 数据生成 typescript 类型支持的 接口 请求方法文件，包括了 后台定义的数据模型

const { generate, ApiGenerator } = require('swagger-api-helper');
const path = require('path');

const outputPath = path.join(__dirname, './services');
const urls = [
    ['https://petstore.swagger.io/v2/swagger.json', 'swaggerDirname'],
    [`https://petstore.swagger.io/v2/swagger.json`, 'swaggerDirname2'],
];

const options = {
    // swagger json url 地址
    urls,
    // 生成的文件 输入路径
    outputPath,
    // 用作生成文件的 别名
    tagAlias: {
        pet: 'petAlias',
    },
    // 自定义 import 模块的 字符串
    // extraImport: '',
    // 自定义 导出的方法 () => string
    // renderFunction: () => '',
    // 请求 swagger json url 的参数配置，设置请求权限等
    fetchOptions: {
        headers: {
            Authorization: 'Basic YWRtaW46dENmcWU4JEph',
        },
    },
    // 需要生成的接口(使用 tag 来匹配) 优先级大于 exclude
    // include?: RegExp | string[];
    // 不需要生成的接口(使用 tag 来匹配)
    // exclude?: RegExp | string[];
};

// 第一种方式
generate(options).then(message => {
    console.log(message);
});

/**
 * 第二种方式
 * 拆分了 发起请求 和 生成文件
 */

(async () {
    const apiGenerator = new ApiGenerator(options);
    await apiGenerator.fetch();
    const messages = await apiGenerator.generate();
})()

generate options

| 字段 | 类型 | 必填 | 默认值 | 描述 | | -------------- | ------------------------------------------------------------------------------------ | ---- | ------ | -------------------------------------------------------------------- | | urls | string[] | [string, string, { headers, query, method, body }][] | 是 | - | 单个 url 为数组时，第二个属性为生成文件的名称, 第三个属性为 请求属性 | | fetchOptions | { headers, query, method, body } | 否 | - | swagger 请求 属性 包括 header, body, method, query | | extraImport | string | 否 | - | 生成文件的顶部 import 字符串, 自定义 renderFunction 时可能需要 | | renderFunction | { options: RenderFunctionOptions, path: CustomPath } 参考 src/generate/interfaces.ts | 否 | - | 自定义生成的请求方法 | | tagAlias | { [key: string]: string } | 否 | - | 生成的文件名默认使用 tag，配置 tagAlias 能修改生成的文件名称 | | outputPath | string | 是 | - | 生成文件输出的路径 | | include | RegExp | string[] | 否 | - | 需要生成的接口(使用 tag 来匹配) 优先级大于 exclude | | exclude | RegExp | string[] | 否 | - | 不需要生成的接口(使用 tag 来匹配) |

| hasBasePath | boolean | 否 | true | 生成的 API 接口中 url 属性是否需要携带 swagger 中的 basePath | | hasExtraFetchOptions | string | 否 | true | 发送请求时是否需要传入自定义的属性, 为 false 时, importExtraFetchOptions 不会被调用 | | importRequest | (filename: string) => string | 否 | () => import request from '@/utils/request'; | 返回 导入 request 的字符串, request 用来发请求的方法 | | importStringify | (filename: string) => string | 否 | () => import stringify from '@/utils/stringify'; | 返回 导入 stringify 方法的字符串, stringify 用来处理 url 上的 query 值 | | importExtraFetchOptions | (filename: string) => string | 否 | () => import { ExtraFetchOptions } from '@/types'; | 返回 导入 ExtraFetchOptions 的字符串 |

部分生成的文件内容

import { stringify } from '../../utils';
import { request } from '../../utils';
import { ExtraFetchOptions } from '../../utils';
import { Pet } from './interfaces';

export interface PostPetPayload extends ExtraFetchOptions {
    /**
     * Pet object that needs to be added to the store
     */
    body: Pet;
}

/**
 * Add a new pet to the store
 *
 */
export async function postPet(payload: PostPetPayload) {
    const { body, ...extraFetchOptions } = payload;
    return request<undefined>(`/pet`,
        {
            ...extraFetchOptions,
            method: 'post',
            body,
        }
    );
}

// ./interfaces
export interface Pet {
	id?: number
	category?: Category
	name: string	//  example: "doggie"
	photoUrls: Array<string>
	tags?: Array<Tag>
	status?: 'available' | 'pending' | 'sold'	// pet status in the store
}