api-see vscode 插件

将指定的 swagger 模块或者接口，转换为 ts 文件和请求方法文件。git

功能

右键菜单：

• swagger【接口】TS化
• swagger【模块】TS化
• swagger【请求】更新
• swagger【基类】TS更新

1. 选择 swagger 服务名称
2. 选择 swagger 接口/模块
3. 生成请求方法
4. 更新当前ts类型文件引用的swagger基类

服务端swagger接口更新的时候，请使用swagger【基类】TS更新更新, 接口删除的时请使用swagger【请求】更新更新请求方法

文件生成中的时候，请勿保存当前文件

文件结构如下：

xxx/actions
├── goods.ts            // 右键菜单点击后 swagger 生成的请求类型
└── goods-action.ts     // 同时生成对应的请求方法

src
├── swagger-base        // swagger基累会被保存到`src/swagger-base`下面
└── xxxserviceName.ts   // swagger xx 服务公共类型

项目根目录必须创建src文件，便于swagger-base文件的创建

要求

1. 请求类型的文件的头部需要添加 “@swagger”的注释

/** @swagger */

2. 根目录配置 api.config.js 文件

AsyncGetSwagger

swaggers 项配置支持传入异步函数获取swagger应用地址， 异步方式下还需要配置serviceNames

/**
 * 异步获取
 * @param1         某个服务的名称
 * @param2 {{
 *  fetchData,    含异常机制处理的node-fetch
 *  showError   	vsCode错误 提示 传入字符串
 * }}
 * @returns  swaggers如{ serviceNamexx: "http://xxxxxxxxx:8080/v2/api-docs?group=xxx"}
 */
async function getSwaggers(serviceName, { fetchData, showError }) {...}

MakeService

/**
 * 请求方法拼装
 * @param2 {{
 *  fileNameOrigin,      引用类型的文件名称
 *  def                  对引用请求TS类型描述的数组
 * }}
 * @returns  string    codeString
 */
async function makeService({ def, fileNameOrigin }) {
    // def 的数组项
    // {
    //   description: '接口描述',
    //   introduce: '接口介绍',
    //   method: 'get',
    //   serviceName: 'xxx服务',
    //   properties: {
    //     response: {
    //       type: 'string' | 'object' | 'boolean' ......,
    //       data: '具体数据，根据type类型的结构'
    //     },
    //     request: {
    //       type: 'string' | 'object' | 'boolean' ......,
    //       data: '具体数据，根据type类型的结构'
    //     },
    //   },
    // }
}

DetaultMakeService

默认拼装请求的函数

module.exports = {
  markeService: function ({ def, fileNameOrigin }) {
    let IMPORT_TYPES = [];
    let SERVICES = "";
    let code = `
  import { zApi } from '@dian/app-utils'
  IMPORT_TYPES
  
  SERVICES
    `;
    for (const key in def) {
      const item = def[key];
      // @ts-ignore
      if (key.includes("Record<string") || !item.url || !item.method) continue;
      IMPORT_TYPES.push(key);
      // @ts-ignore
      const method = item.method;
      // @ts-ignore
      const description = item.description || "--";
      // @ts-ignore
      const url = `/${item.serviceName}${item.url}`;
      let responseTT = "";
      if (
        item?.properties?.response?.type === "object" &&
        item?.properties?.response?.properties?.data
      ) {
        responseTT = `<${key}['response']['data']>`;
      }

      SERVICES += `/** ${description} */ \n`;
      SERVICES += `export async function ${key}Service (params: ${key}['request']) {
        const data = await zApi.${method}${responseTT}('${url}', { params })
        return data
      }\n\n`;
    }

    code = code.replace(
      "IMPORT_TYPES",
      `import type { ${IMPORT_TYPES.join(",")} } from './${fileNameOrigin}'`
    );
    code = code.replace("SERVICES", SERVICES);

    return code;
  },
};

生成 ts 的结构如下：

/**
 * shopList
 * @url /test/shopList
 * @method get
 * @introduce --
 * @serciceName xxxx
 */
export type ItestTestShopList = {
  request: {
    /**
     * @description contractId
     */
    contractId: number;
  };
  response: number;
};