@winner-fed/hep-engine

hep swagger typescript API

Usage no npm install needed!

<script type="module">
  import winnerFedHepEngine from 'https://cdn.skypack.dev/@winner-fed/hep-engine';
</script>

README

Hep - 前端数据层服务解决方案

介绍

Hep 把 swagger 接口文档平台,转换成 Hep 元数据。Hep 利用接口元数据,可以高度定制化生成前端接口层代码。

使用

  • 首先确保项目中存在 hep.config.json 文件。可以使用 hep 进行创建,安装命令如下:
# npm
npm i -g @winner-fed/hep-engine
# yarn
yarn add global @winner-fed/hep-engine
  • 具体功能使用
    • 同步远程数据源
    • 生成前端所需服务请求接口代码

配置文件 hep.config.json 字段说明

originUrl

值类型:string

描述:接口平台提供数据源的 open api url 或者文件路径,格式为 json 或者 yaml。目前只支持 Swagger。如 "https://petstore.swagger.io/v2/swagger.json"

languageType

值类型:string 可选值:'javaScript' | 'typeScript' 描述:生成的代码语言类型

outDir

值类型:string

描述: 生成代码的存放路径,使用相对路径即可。如:"./src/api"

templatePath

值类型:string

描述:指定自定义代码生成器的路径(使用相对路径指定)。一旦指定,hep 将即刻生成一份默认的自定义代码生成器。自定义代码生成器是一份 ts 文件,通过覆盖默认的代码生成器,来自定义生成代码。默认的代码生成器包含两个类,一个负责管理目录结构,一个负责管理目录结构每个文件如何生成代码。自定义代码生成器通过继承这两个类(类型完美,可以查看提示和含义),覆盖对应的代码来达到自定义的目的。

示例:可以参看示例 demo 中的 template。

prettierConfig

值类型:object

描述:生成的代码会用 prettier 来美化。此处配置 prettier 的配置项即可,具体可以参考 prettier 文档

usingMultipleOrigins

值类型:boolean

描述:hep 支持一个项目中配置多个 Swagger 来源。此处配置是否启用多数据源

origins

值类型:array

描述:配置每个数据来源

配置项:

{
  "originType": "SwaggerV2 | SwaggerV3", // 注:暂不支持 SwaggerV1
  "originUrl": string,
  "name": string,
  "usingOperationId": boolean,
  "transformPath"?: string,
  "fetchMethodPath"?: string
}

示例:

"origins": [{
  "name": "pet",
  "originUrl": "",
}, {
  "name": "fruit",
  "originUrl": ""
}]

transformPath

值类型:string

描述:可选项。指定数据源预处理路径(使用相对路径指定)。一旦指定,hep 将生成一份默认的数据预处理器。hep 将 Swagger.json 数据转换为内部标准数据源之后会尝试调用由transformPath指定的转换程序,这样用户就有机会对数据进行一些处理。

数据预处理器示例:

// transfrom.ts 根据 Mod.name进行过滤
import { StandardDataSource } from 'hep-engine';

export default function transform(data: StandardDataSource) {
  if (data.name === 'fooapi') {
    const filterMods = ['modName1', 'modName2', 'modName3'];
    let { mods, baseClasses } = filterModsAndBaseClass(filterMods, data);
    data.mods = mods;
    data.baseClasses = baseClasses;
  }
  return data;
}

/**
 * 过滤mod及所依赖的baseClass
 * @param filterMods Mod.name数组
 * @param data StandardDataSource
 */
function filterModsAndBaseClass(filterMods: string[], data: StandardDataSource) {
  let mods = data.mods.filter(mod => {
    return filterMods.includes(mod.name);
  });
  // 获取所有typeName
  let typeNames = JSON.stringify(mods).match(/"typeName":".+?"/g);

  typeNames = Array.from(new Set(typeNames)) // 去重
    // 取typeName的值
    .map(item => item.split(':')[1].replace(/\"/g, ''));

  // 过滤baseClasses
  let baseClasses = data.baseClasses.filter(cls => typeNames.includes(cls.name));

  return { mods, baseClasses };
}

fetchMethodPath

值类型:string

描述: 可选项, 相对项目根目录路径。用于 Swagger 数据源需要登录才能请求成功的场景,可指定获取 Swagger 源数据的方法。默认为 node-fetch 的 fetch 方法,可通过自定义 fetch 方法获取带鉴权的接口的文档

示例:

注意:此文件目前只能使用 .ts 后缀

// ./myFetchMethod.ts
import axios from 'axios';

export default async function(url: string): Promise<string> {
  const { data } = await axios.post('/api/login', {
    username: 'my_name',
    password: '123456'
  });

  return axios
    .get(url, {
      headers: {
        Authorization: data.token
      }
    })
    .then(res => JSON.stringify(res.data));
}

配置项示例:

注意:路径字段不需要加 .ts 后缀

{
  // ...
  "fetchMethodPath": "./myFetchMethod", 
}

mocks

值类型:object

子字段:

  • 字段名:"enable" 类型:boolean 默认值: true 含义:是否生效

  • 字段名:"basePath" 类型:string 默认值:"" 含义:接口的 basePath

  • 字段名: "port" 类型:string 默认值:8080 含义:mocks 服务的端口号

  • 字段名 "wrapper" 类型:string 默认值:"{"code": 0, "data": {response}, "message": ""}" 含义:接口返回结构,hep 可以计算返回数据类型(比如此处会替换到 {response}),此处可以指定接口返回结构。

如:

{
  "mocks": {
    "enable": true,
    "basePath": "",
    "port": 8080,
    "wrapper": "{\"code\": 0, \"data\": {response}, \"message\": \"\"}"
  }
}

templateType

值类型:string

可选值:'fetch' | 'hooks'

描述:可选项。用于生成 hep 内置模板。配置该项时,一旦检测到本地模板文件不存在将自动使用配置的模板类型生成模板文件。