@lhy-meta-web/open-api v0.1.1

@lhy-meta-web/open-api

根据open api规范文档生成typescript接口文件，当前只支持open api v2版本，v3将在后续版本中支持

快速开始

安装

  npm install -g @lhy-meta-web/open-api

  // 或者
  yarn install -g @lhy-meta-web/open-api

  // 或者
  pnpm install -g @lhy-meta-web/open-api

使用

// typescript
import { GeneratorV2 } from '@lhy-meta-web/open-api'
// javascript
const { GeneratorV2 } = require('@lhy-meta-web/open-api')

const generator = new GeneratorV2({
  api: 'open api v2的访问地址，可在swagger文档的http请求中找到',
  template: {
    outputDir: './dist-api',
    clearOutputDir: true,
  },
})

generator.build()

配置

GeneratorConfig

GeneratorV2Config extends GeneratorConfig

TemplateConfig 模板配置

GeneratorFormatter 包路径配置

export const ResourceFormatter = {
  // 小驼峰
  Hump: 'hump',
  // 大驼峰
  Pascal: 'pascal',
  // 中划线
  Hyphen: 'hyphen',
  // 下划线
  Snake: 'snake',
} as const
export type ResourceFormatter = ConstType<typeof ResourceFormatter>
export type ResourceCodeNameFormatter = Exclude<ResourceFormatter, typeof ResourceFormatter.Hyphen>

GeneratorPackage 包路径配置

GeneratorLogger 日志配置

export const LoggerLevel = {
  Info: 'info',
  Warn: 'warn',
  Error: 'error',
} as const
export type LoggerLevel = ConstType<typeof LoggerLevel>

执行流程

• 从options.api读取Document json
• 将Document json转换为Resource(v2、v3差异在此)
• 根据配置从Template中获取模板组文件(可自定义扩展)
• 根据模板组文件读取对应的模板编译器(可自定义扩展)
• 根据配置项生成模板编译Context上下文(可配置扩展)
• 执行编译器并将编译后的文本写入文件

Class拆分

@lhy-meta-web/open-api会自动根据Document json中的所有url计算出最长公共子路径，并以移除掉该公共路径后的下一级路径作为Class分类。

例：

• v1/api/user/save
• v1/api/user/update
• v1/api/role/update
• v1/api/menu/page

=> 最长公共子路径: v1/api/，得到Class分类

• user
  • save
  • update
• role
  • update
• menu
  • page

模板

@lhy-meta-web/open-api采用nunjucks作为模板编译引擎，并内置了一套默认模板组，包含

• class.njk
• enum.njk
• model.njk

模板文件类型

• TemplateFileType.Model (open api中定义好的模型)
• TemplateFileType.Enum (枚举，v2中的枚举是每个Model或ParameterModel的属性中独立生成，v3中可使用重用枚举)
• TemplateFileType.ParameterModel (针对Path、Query、FormData而新生成的参数模型)
• TemplateFileType.Class (用于多个Api static挂载的Class)

自定义模板

// 注册模板组
Template.registryGroup('自定义模板组名称', {
  files: [
    {
      type: TemplateFileType.Model,
      path: './default/model.njk',
    },
    {
      type: TemplateFileType.Enum,
      path: './default/enum.njk',
    },
    {
      type: TemplateFileType.ParameterModel,
      path: './default/model.njk',
    },
    {
      type: TemplateFileType.Class,
      path: './default/class.njk',
    },
  ],
})

// 然后在配置中指定使用自己的模板组
const generator = new GeneratorV2({
  api: 'open api v2的访问地址，可在swagger文档的http请求中找到',
  template: {
    groupName: '自定义模板组名称',
    outputDir: './dist-api',
    clearOutputDir: true,
  },
})

模板编译器

模板编译器是针对模板文件类型的编译器

@lhy-meta-web/open-api内置了默认的模板编译器，可自定义覆盖默认编译器

import { Template } from '@lhy-meta-web/open-api'
import nunjucks from 'nunjucks'

Template.registryCompiler(
  TemplateFileType.Model,
  (templateContent: string, context: TemplateCompilerContext<typeof TemplateFileType.Model>, resource, config) => {
    return nunjucks.renderString(templateContent, context)
  }
)

自定义TS基础类型解析器

import { TSTypeResolverV2 } from '@lhy-meta-web/open-api'

// 注意TSTypeResolverV2.mapping是只读属性
console.log(TSTypeResolverV2.mapping)

// 以下是默认值
//   {
//     object: 'Record<string, unknown>',
//     string: 'string',
//     integer: 'number',
//     int: 'number',
//     long: 'number',
//     double: 'number',
//     boolean: 'boolean',
//     Map: 'Record',
//     List: 'Array',
//     Void: 'void',
//     file: ' File',
//   }

Object.assign(TSTypeResolverV2.mapping, {
  // ...编写自己的类型映射
})

注意事项

• 接口文档中的泛型对象不能使用多泛型，只能是单泛型结构。如: User<Integer, String>是不允许的，User是允许的
• 所有的泛型必须明确的指定类型，否则会被解析成unknown
• 应避免使用Object、JSON、Map等数据类型，尽可能使用明确的类型，此类均被解析成Record<string, unknown>
• 文件上传接口指定@ApiImplicitParams({@ApiImplicitParam(name = "file", dataType = "MultipartFile")})，在swagger文档上能显示 consumes "multipart/form-data"即可
• 返回文件流接口指定produces = MediaType.APPLICATION_OCTET_STREAM_VALUE，在swagger文档上能显示 produces "application/octet-stream"即可

意见或建议

可发送邮件至邮箱810422646@qq.com，标题请明确包含@lhy-meta-web/open-api字样