1.2 Example

1{
2  "url": "./api.json", // 文件路径
3  "remoteUrl": "http://**", // url
4  "requestConfig": {
5    "url": "./api.json" // 文件路径或url
6    // 以下所有 request 支持的参数
7    // headers?: Headers;
8    // baseUrl?: string;
9    // callback?: RequestCallback;
10    // jar?: CookieJar | boolean;
11    // formData?: { [key: string]: any };
12    // form?: { [key: string]: any } | string;
13    // auth?: AuthOptions;
14    // oauth?: OAuthOptions;
15    // aws?: AWSOptions;
16    // hawk?: HawkOptions;
17    // qs?: any;
18    // qsStringifyOptions?: any;
19    // qsParseOptions?: any;
20    // json?: any;
21    // jsonReviver?: (key: string, value: any) => any;
22    // jsonReplacer?: (key: string, value: any) => any;
23    // multipart?: RequestPart[] | Multipart;
24    // agent?: http.Agent | https.Agent;
25    // agentOptions?: http.AgentOptions | https.AgentOptions;
26    // agentClass?: any;
27    // forever?: any;
28    // host?: string;
29    // port?: number;
30    // method?: string;
31    // body?: any;
32    // family?: 4 | 6;
33    // followRedirect?: boolean | ((response: http.IncomingMessage) => boolean);
34    // followAllRedirects?: boolean;
35    // followOriginalHttpMethod?: boolean;
36    // maxRedirects?: number;
37    // removeRefererHeader?: boolean;
38    // encoding?: string | null;
39    // pool?: any;
40    // timeout?: number;
41    // localAddress?: string;
42    // proxy?: any;
43    // tunnel?: boolean;
44    // strictSSL?: boolean;
45    // rejectUnauthorized?: boolean;
46    // time?: boolean;
47    // gzip?: boolean;
48    // preambleCRLF?: boolean;
49    // postambleCRLF?: boolean;
50    // withCredentials?: boolean;
51    // key?: Buffer;
52    // cert?: Buffer;
53    // passphrase?: string;
54    // ca?: string | Buffer | string[] | Buffer[];
55    // har?: HttpArchiveRequest;
56    // useQuerystring?: boolean;
57  },
58  "type": "yapi",
59  "yapiConfig": {
60    "required": false,
61    "bodyJsonRequired": false,
62    "categoryMap": {
63      "中文": "English" // yapi 接口分类中英文映射
64    }
65  },
66  "swaggerParser": {
67    "-o": "tmp/services"
68  },
69  "validateResponse": false, // 是否生成校验逻辑
70  "guardConfig": {
71    // + strict 严格模式
72    //    - 校验 swagger tags【yapi 接口分类】是否是纯英文
73    //    - 方法名使用 http method + url 驼峰形式
74    //    - 新项目采用
75    // + safe 安全模式
76    //    - 方法名使用 http method + url 驼峰形式
77    //    - 老项目升级，不会校验 tags，会生成方法调用替换映射表
78    // + 默认
79    //    - http method + url => operationId 映射锁定
80    //    - 老项目维持现状
81    "mode": "strict",
82    // swagger 处理重复 operationId 逻辑有风险，因此需要锁定映射关系
83    "methodUrl2OperationIdMap": {
84      "get /api/xxx/xxx": "operationId"
85    }
86  }
87}

1.3 生成 service 代码

命令行

1  ./node_modules/.bin/sm2tsservice # 使用默认配置
2  ./node_modules/.bin/sm2tsservice -c config.json # 指定配置文件
3  ./node_modules/.bin/sm2tsservice --clear # 清空上次生成产物
4  ./node_modules/.bin/sm2tsservice --quiet # 自动全量使用远程文档，不显示 diff & merge 页面
5  ./node_modules/.bin/sm2tsservice --models # 仅生成 models
6  ./node_modules/.bin/sm2tsservice --models --apis # 仅生成 models & apis
7  ./node_modules/.bin/sm2tsservice --typeScriptDataFile TypeSciptData.json # 仅生成类型信息 json 到 TypeSciptData.json

npm run

写入 package.json，通过 npm run api 使用

1{
2  "scripts": {
3    "api": "sm2tsservice --clear"
4  }
5}

2. ajax 接口

实现 ajax 类【如果使用的 axios，且后端返回数据结构遵循 { code?:number;message?:string;result: any }】

详情 tkit-ajax

3. 增量更新

自 @3.1.* 版本起，支持增量更新

流程

• 配置文件变更
  • url - 必须指向本地 swagger 文件【如文件不存在，在获取 remoteUrl 指定地址内容后，创建该文件
  • remoteUrl - url 地址，即之前的 url
• 执行 CLI 生成代码
• CLI 对本地 swagger 文件和远程 swagger 文件进行 DIFF
  • 有差异
    • 打开浏览器，人工选择需要同步的差异，点保存
    • CLI patch delta
  • 无差异
    • 直接下一步
• CLI 生成 service 代码

4. CHANGELOG

import CHANGELOG from './CHANGELOG.md';