如何通过swagger得到ts所需要的interface+tsdoc

一、前言

在2020年底的时候开始注重定义类型的tsdoc书写的时候。如果当前是一个字段比较多的详情接口，我们定义interface和tsdoc注释就很麻烦，写一个字段复制一段字段描述，可能要耗费好几分钟。会越来越不想写注释。

二、分析

其实我们再用swagger上联调接口（其他工具也类似），你会发现接口的出参，有类型，有注释（如下）。那它这里的数据是怎么得到的呢，打开控制台，你会发现 /swagger-resources，出参msg[0].location,是下一个请求的接口地址，然后得到需要的数据，解析这里的数据即可。

/*
  // swagger出参类型
  Response Class (Status 200)
  OK
  Modal
  ReportConfigDTO {
    isGlobalConfig (integer, optional): 1/0 是否全局配置（当是全局配置时，tenantId = -1） ,
    reportConfigId (string, optional): 报告单配置id（更新时传入） ,
    reportForms (Array[ReportFormConfigDTO], optional): 报告单表单配置数组 ,
    sourceTenantId (string, optional)
  }
*/

三、行动起来

• webpack插件 swagger-ts-plugin
• vscode插件 vscode-swagger2ts-plugin

四、插件功能

根据用户的配置情况会在项目根目录下生成swagger2ts文件，下面有多个服务，每个服务有两个文件

├── swagger2ts
	├── [serviceName1]
 		├── interface.d.ts
		└── paths.ts
	├── [serviceName2]
		├── interface.d.ts
		└── paths.ts
	└── ...

1. /swagger2ts/service-xxx/paths.ts文件
返回当前服务的所有接口的请求方式和data类型（来自 interface.d.ts）

2. /swagger2ts/service-xxx/interface.d.ts文件
当前服务的所有接口的所有定义，存在被引用（f12 或者 ctrl+单击）
每个interface都有自己类型和注释

*不建议直接使用生成的文件，根据自己的需求，修改和复制到你需要的地方

配置及使用 (三选一即可)

参数

1、webpack插件使用

webpack.config.js

const Swapper2TsPlugin = require("swagger-ts-plugin");
/**
 * outputPath 输出地址
 * appUrl 必须是贵公司的eureka所有服务列表地址 http://eureka.dev.com:1111/eureka/apps 
 * 当前地址返回的是xml格式数据，插件会处理
 */
// 原本想解析项目中的所有文件夹，自动的检查出服务名称，服务地址，实际做的时候发现不是很好做
// 所有它实际上不算一个webpack插件，
module.exports = {
    plugins: [
        new Swapper2TsPlugin({
            outputPath: path.resolve(__dirname, "../"),
            // v1.1.11 以后支持这种混合类型
            serverList: [
                "trialpartner-web",
                "sms-service",
                {
                    serviceName: "xxx-service",
                    serviceUrl: "http://172.12.12.111:8001/",
                },
            ],
            // 如果serverList中只提供服务名称，则必须提供 http://eureka.dev.com:1111(eureka地址)+ /eureka/apps
            appUrl: "http://eureka.dev.com:1111/eureka/apps",
        }),
    ],
};

2、作为工具使用

// 因为swagger-ts-plugin插件也直接暴露出build方法，开发者可以直接调用
// npm scripts 增加一条命名，"build:ts":"node xxx.js";

// 创建一个xxx.js;
new Swapper2TsPlugin({
    /* 配置，如上 */
}).build();

// 执行 yarn build:ts就能run起来了

3、vscode插件

1. vscode插件市场找到 vscode-swagger2ts-plugin 安装

2. 配置，请打开 文件-> 首选项 -> 设置， 找到swagger-ts-plugin;

• 请配置eureka服务列表的接口 appUrl，如http://eureka地址/eureka/apps
• 请配置服务名称和服务对象（如下）。

// vscode插件是每项单独配置，这里的配置等同于serverList
"swagger-ts-plugin.serviceList": [
    {
        "serviceName": "xxx-service",
        "serviceUrl": "http://172.20.37.153:8000/",
    },
    "sms-service"
]

3. 使用 ctrl+shift+p 打开Command Palette，输入 swagger2ts 回车。

4. 请注意如果是新开的vscode窗口未选择文件是不会有任何文件生成。如果你的配置没有问题，当前窗口也选择了文件项目。你将在文件根目录得到一个swagger2ts文件夹，包含多个子文件夹数量等于配置的服务数量。

5. vscode插件额外给根目录的.gitignore文件添加忽略/swagger2ts的配置。

最后

第一次写文章,有很多不足的地方，有任何建议可以找我邮箱1543259203@qq.com。

如果觉得还好的话，给个⭐️⭐️ 谢谢啦~ swagger-ts-plugin

vscode-swagger2ts-plugin