欢迎使用 swagger-to-ts-mods 👋

中文文档 | English

swagger-to-ts-mods 根据 swagger文档生成typescript类型声明及api调用函数

安装

# 使用 npm
npm install swagger-to-ts-mods

# 使用 yarn
yarn add swagger-to-ts-mods

使用

# 生成配置文件
$ s2t setup

# 生成类型声明及api函数
$ s2t generate

# 查看说明
$ s2t [command] -h

生成示例

API.d.ts

declare namespace API {
  namespace User {
    interface Exception {
      cause?: Throwable;
      localizedMessage?: string;
      message?: string;
      stackTrace?: StackTraceElement[];
      suppressed?: Throwable[];
    }
    interface RestVo {
      code?: number;
      data?: { ... };
      exception?: Exception;
      message?: string;
    }
    /** login */
    namespace postAuthsLogin {
      type Query = {
        /** checkcode */
        code?: string;
        /** phone */
        mobile?: string;
        /** password */
        password?: string;
        /** account */
        username?: string;
      };

      type Response = RestVo;
    }
  }
  
  namespace File { ... }
  ...
}

some-operation.ts

e.g. postAuthsLogin.ts

import uRequest from "@/services";

import Inter = API.User.postAuthsLogin;

/** login */
export function postAuthsLogin(query: Inter.Query): Promise<Inter.Response> {
  return uRequest<Inter.Response>("/api/v1/auths/login", {
    method: "post",
    params: query,
  });
}

命令

$ s2t setup [outputPath]

生成配置文件

参数	默认值	是否必填	说明
outputPath	"./s2t.config.json"	否	指定配置文件输出地址

$ s2t generate [configPath]

根据配置文件生成目标文件

参数	默认值	是否必填	说明
configPath	"./s2t.config.json"	否	用于指定配置文件地址

配置文件

s2t.config.json

key	类型	默认值	是否必填	说明
request	RequestConfig	见RequestConfig	是	通用api请求设置
handleUnknownType	unknown | generic | any	unknown	否	如何处理未知类型 （暂未实现）
outputDir	Path	"./services"	否	生成文件的目录
templateDir	Path	内置	否	生成类型声明及api函数时的模板文件目录
origins	OriginConfig[]	无	是	指定swagger文档地址来源

OriginConfig

key	类型	默认值	是否必填	说明
origin	string	无	是	swagger文档地址
originName	string	无	是	指定该文档名称
request	RequestConfig	见RequestConfig	否	为该文档指定特殊请求设置

RequestConfig

生成api函数时指定基类函数的引入方式

如： import ${methodName} from "${filePath}"

key	类型	默认值	是否必填	说明
filePath	Path	"@/request"	否	指定本地接口调用函数
methodName	string	request	否	指定导出的函数名
default	boolean	true	否	方法是否为默认导出

模板文件

使用mustache作为渲染引擎

模板	内容	说明
API.d.mustache	内置	声明文件模板
operation.mustache	内置	api模板

TODOS:

• 支持$ref中远程文档的解析
• 处理未知类型时，支持泛型