apitots-swaggers swagger自动生成ts

当前端web项目中应用了ts，我们不可能对成千上百的接口进行 interface的类型定义,那样效率是极低的，但是我们又需要ts智能友好的提示信息，该怎么办？这是我们必须要面对的问题。

介绍

根据swagger.json地址迅速生成ts接口，以及相关请求响应参的interface模块命令行工具。且支持swagger的V2、V3版本。其宗旨是利用swagger接口文档让前端的效率变得更高，接口的请求参、响应参以及接口命名将不在需要手动引入，让前端更聚焦在业务功能的开发，接口将全面与swagger进行同步。

快速入门

1.安装

npm i apitots-swaggers -g 或者yarn add apitots-swaggers -g

ps:

全局安装能让命令在任何地方能运行，如果只安装在项目上，可执行文件将被安装到 node_modules/.bin下，通常这个目录通常不会被加入系统的 PATH 环境变量，所以就需要在script内定义脚本进行运行方可成功跑通脚本，如下：

"scripts": {
    "apits:init": "apits init",
    "apits:gen": "apits tots",
  }

全局安装则不需要，可直接运行apits命令，两种方式可任意选择。

2.帮助文档

输入apits,根据命令提示进行操作，如图。

创建配置文件

apits init 

执行配置文件生成代码

apits tots

强制重新生成所有代码（不使用增量更新）

apits tots --force

执行完成完成如图

3.API说明

| 参数 | 说明 | 类型 | 是否必填 | 默认值 | |:----------:|:----------:|:----------:|:----------:|:----------:| | serverUrl | 服务地址，此处填其 json 地址 | string | 是 | | | requestInstanceUrl | 请求文件路径(request路径) | string | 否 | axios | | outputFilePath | 输出文件路径 | string | 否 | src/api | | ImportBaseURL | 设置接口的baseURL导入地址 | string | 否，搭配baseURL | | | baseURL | 设置接口的baseURL | string | 否，搭配ImportBaseURL | | | includeTags | 包含的接口Tag | string | 否 | [] | | excludeTags | 排除的接口Tag | string | 否| [] | | prefix | 添加前缀，如代理请求模式，所有请求均请求到指定接口 | string | 否 | | | name | 服务名称 (多服务配置) | string | 否 | |

4.示例

单服务配置：

多服务配置：

{
  "services": [
    {
      "name": "service1",
      "serverUrl": "http://example1.com/v2/api-docs",
      "requestInstanceUrl": "axios",
      "outputFilePath": "src/api/service1",
      "prefix": "/api1"
    },
    {
      "name": "service2",
      "serverUrl": "http://example2.com/v2/api-docs",
      "requestInstanceUrl": "axios",
      "outputFilePath": "src/api/service2",
      "prefix": "/api2"
    }
  ]
}

结果：

5.多服务管理命令

# 添加新服务配置
apits add-service

# 列出所有服务配置
apits list-services

# 移除服务配置
apits remove-service --name serviceName
# 或者不带参数，通过交互方式选择要删除的服务
apits remove-service

6.增量更新

为了提高生成效率，从v1.2.0开始，工具默认使用增量更新功能。这意味着：

• 只有API定义发生变化的文件才会被重新生成
• 会在项目根目录创建.apits-cache目录保存API文件哈希值
• 大幅减少生成时间和避免不必要的文件变更

如果需要强制重新生成所有文件，可以使用--force选项：

# 强制重新生成所有文件
apits tots --force

输出信息中会显示API总数和实际更新的文件数：

✔ 接口生成完成: 共 184个接口, 更新了 5个接口, 路径在src/api/service2

注意：

1.如出现生成出错，请检查后端返回的json是否服务标准。

2.生成格式会默认配置，如果本地有配置.prettierrc，会自动读取.prettierrc内配置，根据配置生成具体的代码格式

3.配置baseURL的文件需要指定文件路径，内容全量导出。

4.同时支持单服务和多服务配置，可以根据需要选择使用方式。多服务配置不会影响现有单服务配置的使用。