/service-builder

A tool for generating services based on swagger documentation.

Primary LanguageJavaScript

sv-builder

一款基于swagger文档生成service层的工具

介绍

service-builder支持swagger1.x和2.x版本，使用时仅需要简单配置就可以生成基于路径的service，其支持自定义渲染模板，生成的结果是语言无关的(需要 prettier 支持)。

使用

基本方式

  1. npm install sv-builder sv-builder-template --save-dev
  2. 在项目根目录新建.service-config.json文件，进行配置，一个简单的例子如下：
{
  "originUrl": "http://apidoc.xx.com/gen/v2/api-docs", // 远程swagger文档地址
  "sourcePath": "./service.json", // 本地swagger文档
  "outDir": "./service", // service 输入目录
  "templateClass": "TemplateClass.js", // 模板文件名
  "ext": ".ts" // 输出文件扩展名
}
  1. 在根目录新建模板文件config.templateClass指定的同名文件，一个简易的写法可以是：
const Template = require('sv-builder-template')

class MyTemplate extends Template {
  // 必须要实现的方法
  getTemplateContent(doc) {
    const [queryParams, bodyParams] = this.getTypeParams()
    return `
      import request from '@/utils/request'

      type BodyParams = ${bodyParams}
      interface QueryParams {
        ${this.getTypeQueryParams(queryParams)}
      }
      /**
       * ${doc.summary}
       */
      export function ${doc.fileName}(query: QueryParams, body: BodyParams) {
        return request('${doc.url}', '${doc.method}', query, body)
      }
    `
  }
}

module.exports = MyTemplate
  1. 在文件根目录创建.js文件，作为执行入口，
const service = require('sv-builder')

service.run()
  1. 在node(版本>=10.0.0)环境下执行入口文件，service(如果是 ts 的话还将生成相关的类型定义文件api.d.ts)将会生成到指定目录。

CLI（>=1.2.0 版本）推荐

  1. yarn add --dev sv-builder 安装builder
  2. yarn add --dev sv-builder-template 安装模板文件
  3. 在package.json的scripts中添加以下代码
  "scripts": {
    ...
    "builder:init": "sv-builder -i", // 也可以是`sv-builder init`
    "builder:generate": "sv-builder -g" // 也可以是`sv-builder generate`
  },
  1. 运行yarn builder:init初始化，将生成.service-config.json和Template.js两个文件
  2. 按需修改.service-config.json和Template.js
  3. 运行builder:generate生成service

Tips

  • 在originUrl和sourcePath同时配置的情况下，优先使用远程swagger文档。
  • 自定义模板类一定要继承Template类和实现getTemplateContent方法，否则无法生成
  • getTemplateContent(doc)中参数doc类型如下：
interface IDoc {
  summary: string // 接口摘要/注释
  method: string // 请求method类型
  fileName: string // 文件名
  dirName: string // 存放目录
  url: string // 请求地址
  params: parameters[] // 请求参数 见swagger文档 parameters
  doc: any // 某一请求的原始swagger文档
}

更新记录

1.1.0

  • 增加对ts的支持，现在可以生成相关的.d.ts文件，Template类提供了getTypeParams和getTypeQueryParams的方法用于生成参数定义

1.2.0

1.2.2

  • 支持了url中 path 作为参数的情况，例如/api/retail/supplier/goods/group_price/spec_id/by_group_id/{groupId}
  • 针对definition重复进行了去重，解决了.d.ts文件中出现defs.undefined的问题
  • 解决了使用prettier格式化ts报错，修复了函数名可能是保留字/关键字而格式化报错的问题