[开发工具]Swagger转ts工具介绍-Pont

• 背景

接口文档是前后端同学合作的有效交流媒介，但往往会存在前端同学认为后端提供的接口文档与实际情况不一致；后端同学可能会认为编写及维护接口文档会耗费不少精力；随着多个版本迭代，经常来不及更新，接口文档往往很容易就跟不上代码了诸如此类的问题。
前端项目中使用ts，最大的痛点就是类型定义成本极高，且维护成本较高。

• 同类型工具（在服务端使用swagger工具的基础上）

1. swagger-to-ts，swaggts等多个生成typescript interface代码的插件（简单上手好用）
   缺点：只负责ts类型代码的生成，功能较为单一
2. Yeoman 是一个通用型代码生成器脚手架工具，可以创建特定类型的代码文件（配合swagger-2-ts即可实现接口文档转ts到接口请求代码一整套流程）

1. 原理：基于模板
2. 使用方式： 下载api-docs，让用户提供swagger-ui地址，然后计算出api-dos路径 解析json。根据模板生成class文件，Yeoman的模板是基于ejs。
3. 好处：Yeoman提供了提示功能，可以定义prompts，之后通过this.props获取用户参数。方便，易上手，操作成本，学习成本较低

3. Pont：阿里开源的一种前后端桥接工具

1. 功能： 可以把 swagger、rap、dip 等多种接口文档平台，转换成 Pont 元数据。 Pont利用接口元数据，可以高度定制化生成前端接口层代码。 可以生成接口 mock 数据。
2. 优点：功能丰富，社区丰富（阿里的很多大型项目已在使用），遇到问题可快速找到答案。操作简单，学习成本低。

• pont运行介绍：
• pont使用
• vscode插件使用方式：(pont插件一旦检测到有效的pont-config.json文件即可启动）

安装vscode-pont插件
全局安装pont-engine
添加pont-config.json配置文件（可使用pont start命令快速生成）
vscode插件使用方式：

1. sync：重新请求远程接口数据，计算远程与本地接口数据在接口模块和接口返回对象上的差异。
2. all：将本地所有接口模块，接口返回对象与远程数据保持一致。 generate: 重新生成本地代码。
3. interface：快速的接口搜索

• 非vscode使用方式（命令行使用方式）

pont start: 生成pont-config.json
pont check:检测本地的pont-lock.json是否有缺失。
pont ls: 查看所有数据源
pont diff: 监测远程与数据源差异，选择性同步
pont scan: 扫描未使用的接口，需要配置scannedRange

注： pont-config.json主要配置：

originUrl：swagger平台提供的接口url（目前只支持swagger)
originType: 数据源接口类型（SwaggerV2）
outDir: 生成代码的存放路径，使用相对路径
templatePath: 生成接口代码的模版
mock: 是否生成mock数据。

• 需要服务端配合：

• 完整的注释
  • 提供非登录的swagger访问地址。
  • Swagger 必须在每个 Controller 上添加 ApiUseTags装饰器，并且在每个控制器的方法上添加 ApiOperation 装饰器 才能正确输出带 Tags 以及 operationId 的Swagger JSON。Tags 和
    operationId 是 pont 必需的。不然前端生成的pont文件没有mods。

• 感触

工具可提高我们的工作效率，磨刀不误砍柴工，有时候找到一个合适的工具可以让我们事半功倍。