ex-swagger-to-types README

修改于 swagger-to-types

将 Swagger JSON 导出为 Typescript interface

每个接口生成一个 namespace (用于分组,避免重名), 包含 Params, Response, 和一些额外 interface.

预览

Config

SwaggerJsonUrlItem

快捷键

• 搜索接口列表: alt + shift + F

以下为可选配置：

忽略一键更新

在 .d.ts 文件头部注释中添加 @ignore 标识, 可以在一键更新本地接口时忽略当前文件.

/**
 * @name   示例接口
 * @path   /demo/demo-api
 * @method POST
 * @update 10/19/2020, 11:22:53 AM
 * @ignore
 */

Interface 模板

用于在某些特殊场景下定制产出的内容格式。

详细类型参考 TemplateBaseType

示例: 添加分组前缀

编辑 .vscode/swagger-to-types.template.js 文件

function namespace(params) {
  return `${params.groupName.replace(/[\-\n\s\/\\]/g, '_')}_${params.pathName}`
}

module.exports = { namespace }

示例: 将字段名转化为大驼峰

编辑 .vscode/swagger-to-types.template.js 文件

/**
 * 首字母大写
 * @param {String} str
 */
function toUp(str) {
  if (typeof str !== 'string') return ''
  return str.slice(0, 1).toUpperCase() + str.slice(1)
}

function paramsItem(item, params) {
  // 项目标题(swaggerToTypes.swaggerJsonUrl[number].title) 为 demo-1 时忽略定制方案
  if (params.groupName === 'demo-1') return

  return `${toUp(item.name)}${item.required ? ':' : '?:'} ${item.type}`
}

module.exports = { paramsItem }

复制请求函数

配置一个请求函数模板用于快速复制

编辑 .vscode/swagger-to-types.template.js 文件

如果导出了 copyRequest 函数，即可使用此功能

相关按钮将出现在这几个位置：

• 本地接口列表操作按钮
• .d.ts 文件 标题栏操作按钮
• .d.ts 文件 代码行首文字按钮

下面是一个例子：

/**
 * 请求函数模板
 *
 * @param {{
 *  fileName: string
 *  ext: string
 *  filePath: string
 *  name?: string
 *  namespace?: string
 *  path?: string
 *  method?: string
 *  update?: string
 *  ignore?: boolean
 *  savePath?: string
 *  requestParams?: boolean
 *  responseParams?: boolean
 * }} fileInfo
 * @returns
 */
function copyRequest(fileInfo) {
  return [
    `/** ${fileInfo.name} */`,
    `export async function unnamed(params?: ${fileInfo.namespace}.Params, options?: RequestOptions) {`,
    `  return $api`,
    `    .request<${fileInfo.namespace}.Response>('${fileInfo.path}', params, {`,
    `      method: ${fileInfo.method},`,
    `      ...options,`,
    `    })`,
    `    .then((res) => res.content || {})`,
    `}`,
  ]
}

module.exports = {
  // ...
  copyRequest,
}

源代码相关

开发预览调试：在 vscode 中按下 F5 即可。

注意

• 支持 swagger v2 API
• 支持 openapi 3.0.0 (1.1.4 新增)
• 请不要对模板处理函数的参数直接进行赋值操作，这可能产生破坏性影响。