Skip to content

amazecc/swagger-ts-define

Repository files navigation

Swagger TypeScript 类型生成

目前只支持 swagger3.0.0

安装

npm i swagger-ts-define -D

or

yarn add swagger-ts-define -D

配置

根目录创建 swagger-ts-define.config.js,进行配置

const config = {
  /** swagger json schema 地址 */
  docUrl: 'http://example/docs-json',
  /** 类型输出目录,路径相对于根目录 */
  outputDir: 'api',
  /**
   * 对 api url 进行处理,该名称将会作为 interface 的名称前缀
   * @example /web/v1/user/list -> user/list -> interface UserListGetQuery {...}
   */
  getPath: (path) => path.match(/(?<=\/v1\/).+/)[0],
  /** api 调用方法方法来源,将会插入到文件首部 */
  requestFrom: 'import { request } from "src/utils/request";',
  /**
   * 针对 iso8601 时间格式字符串的自定义类型
   * @description 如果在 http 请求返回数据时统一做时间数据转换,比如统一转换为 Date 或者 Moment,那么可以在这里设置对应的类型
   */
  isoString: {
    typeName: 'string', // 'Moment'
    import: '', // 'import { Moment } from 'moment'
  },
};

module.exports = config;

运行

# 项目根目录执行
npx swagger-ts-define

类型说明

类型命名规则

url + method + (query/param/body/response) 得到字符串后进行驼峰命名处理

  • url 可通过配置文件中 getPath 方法进行处理,保留需要的信息
  • method 为请求方式,get/post/delete...
  • query 为 url 参数,例:/users?id=xxx
  • param 为 path 参数,例:/users/{id}
  • body 为请求体参数
  • response 为返回值
  1. 生成的类型分为四大类:UrlGetQuery,UrlGetParam,UrlPostBody,UrlGetResponse

  2. 可自行封装通用 http 请求函数来使用以上生成的类型,在配置文件中配置 requestFrom 即可自动生成接口调用文件

    request(config: { query?: UrlGetQuery, param?: UrlGetParam, body?: UrlPostBody, url: string, method: string, ... }): Promise<UrlGetResponse>

例子

  1. GET /v1/users/{role}?name=xx
export interface V1UsersByRoleGetParam {
  // ...
}

export interface V1UsersByRoleGetQuery {
  // ...
}

export interface V1UsersByRoleGetResponse {
  // ...
}

About

swagger docs-json 生成接口类型声明

Resources

License

Stars

Watchers

Forks

Packages

No packages published