通过swagger生成api请求方法的记录swet-parser 介绍 swet-parser 把各种接口文档数据转换

swet-parser 介绍

swet-parser 把各种接口文档数据转换成 swet 元数据。swet-parser 利用元数据，可以定制化生成前端接口层代码，接口 mock 数据和模型定义。

其中 swagger 数据源 swet-parser 已经提供了默认适配器转换成 swet 元数据

对于尚不支持的数据格式用户可以选择自己提供适配器转换成 swet 元数据

快速开始

1、安装

$ npm i @ad/swet-parser -S

2、使用

swet-parser 使用示例参考：www.baidu.com

// 导出 parser 模块
import { Parser } from '@ad/swet-parser'

/** 
 * 参数一: 原始数据源，swagger 数据源默认支持无需额外提供适配器
 * 参数二: config 配置项，详细说明见配置项
*/
const parser = new Parser(originalData, config)

// 监听错误和警告事件
parser
  .on('error', (errorInfo) => {

  })
  .on('warn', (warnInfo) => {

  })

// 将原始数据转换成元数据并返回元数据
const standardDataSource = parser.transformToStandard()

// 获取所有的模型定义数据
const interfaces = parser.getInterfaceGenerators()

// 获取所有的 service 定义数据
const controllers = parser.getControllers()

// 获取所有的 mock 数据
const allMockData = parser.getAllMockData()

// 获取 service 按模块拆分时的入口文件数据
const serviceEntryCode = parser.getEntryCode()

API

`parser = new Parser(originalData, config)`

创建一个 Parser 实例，传入两个参数：

originalData: Record<string, any>: 原始数据源
config: Config: 配置项

`on`

实例方法，监听实例事件，返回值是实例本身可以链式调用

import { Parser, EventInfoCode } from '@ad/swet-parser'
// config 配置项
import config from './config'
// 原始数据源
import originalData from './data'

const parser = new Parser(originalData, config)

// 监听警告和错误事件
parser
  .on(EventInfoCode.WARN, (warnInfo) => {
    console.log(warnInfo.errorMsg)
  })
  .on(EventInfoCode.Error, () => {
    console.log(errorInfo.errorMsg)
    process.exit(1)
  })

`transformToStandard`

实例方法，将原始数据转换成元数据并返回元数据

import fs from 'fs-extra'
import path from 'path'

// 获取转换后的元数据
const standardDataSource = parser.transformToStandard()

// 将元数据写入文件
const standardJsonPath = path.join(__dirname, './standard.json')

fs.writeFileSync(
  standardJsonPath,
  JSON.stringify(this.standardJson, null, 2)
)

`getInterfaceGenerators`

实例方法，获取通过传入文档生成的模型定义数据

import fs from 'fs-extra'

const interfaceGenerators = this.parser.getInterfaceGenerators()

let code = ''

for (const inter of interfaceGenerators) {
  // 每个模型的定义
  const interfaceItemCode = inter.toCode().content

  code += interfaceItemCode
}

// 将模型定义写入文件
fs.writeFileSync(path.join(__dirname, 'models.d.ts'), code)

`getControllers`

实例方法，获取通过传入文档生成的 service 数据

const controllers = this.parser.getControllers()

// 所有模块的 service 数据
let code = ''
// 记录每个模块的 service 数据
const controllersCode = Object.create(null)

for (const controllerName in controllers) {
  const services = controllers[controllerName]

  // 每个模块的 service 数据
  let serviceCode = '' 

  // 按 controller 模块来生成 service
  for (const service of services) {

    if (supportTs) { // ts 格式 service
      serviceCode += service.toCode()?.content.typescript || ''
      code += service.toCode()?.content.typescript || ''
    } else { // js 格式 service
      serviceCode += service.toCode()?.content.javascript || ''
      code += service.toCode()?.content.javascript || ''
    }

  }
  controllersCode[controllerName] = serviceCode
}

`getAllMockData`

实例方法，获取通过传入文档生成的 mock 数据

import fs from 'fs-extra'
import path from 'path'

const allMockData = parser.getAllMockData()

for (const mockDataArr of Object.values(allMockData)) {
  for (const mockData of mockDataArr) {
    
    const { url, method, content } = mockData
    const finalUrl = path.join(config.baseUrl, url)
    let existData = undefined

    // 判断是否已存在 mock 数据，对于已有的 mock 数据不会覆盖
    if (fs.existsSync(path.join(finalUrl, `${mockData.method}.js`))) {
      const dataFunc = require(path.join(finalUrl, `${method}.js`))
      existData = isFunction(dataFunc) ? dataFunc() : dataFunc
    }

    mockResArr.push({
      method,
      content: content.toCode(existData),
      finalUrl,
      url,
    })
  }
}

`getEntryCode`

实例方法，文件切分的情况下所有 service 入口文件数据

// service 按模块拆分时调用此方法生生成入口文件的数据
const serviceEntryCode = parser.getEntryCode()

配置项

`baseUrl: string`

描述：可选，为 service 生成统一的 url 前缀

`requestHeaders: Record<string, string>`

描述：可选，为 service 添加自定义 headers

`prettierConfig: Record<string, any>`

描述：可选，prettier 配置项

`forceOptional: boolean`

描述：可选，是否强制入参为可选

`level: number`

描述：可选，引用的最大层级，默认值：6

`interfacePrefix: string`

描述：可选，生成 interface name 前缀，默认值：'I'

`serviceFilter: (controllerName: string, operationId: string, path: string, method: string) => boolean`

描述：可选，自定义是否生成 service 函数

`transformFunctionName: (controllerName: string, operationId: string, path: string, method: string) => boolean`

描述：可选，自定义生成 service name

`apiTemplate: () => ({ leadingCode?: string; trailingCode?: string; returnKey?: string })`

描述：可选，mock 数据的预处理，默认值：

apiTemplate: () => {
  return {
    leadingCode: `import axios from 'axios'`,
    trailingCode: '',
    returnKey: 'data'
  }
}

`adapter: AdapterConstructor`

描述：可选，转换原始数据所用适配器，内置 swagger 数据格式适配器

abstract class Adapter {
  abstract transform(): StandardDataSource
}

interface AdapterConstructor {
  new (originalData: Record<string, any>): Adapter
}