前言
随着 RESTful 接口的流行，Swagger 已经成为了前后端联调的重要工具。Swagger 的主要功能是定义 API 的文档和调用协议，这让前后端开发者能够更加便捷地进行联调。
在前端项目中，我们通常需要将后端定义的模型类转换为前端可用的 TypeScript 类。这时候就可以用到 swagger-model-generator-ts 这个工具。
swagger-model-generator-ts 是一个可从 Swagger 文档中获取模型并根据提供的代码生成器生成 TypeScript 类的 npm 包。本篇文章将介绍如何使用 swagger-model-generator-ts 进行模型代码生成。
准备工作
我们将使用官方提供的 Petstore 示例 API 文档进行测试。首先，确保我们已经安装了 Node.js。如果没有安装，可以从 Node.js 官网 下载最新版本进行安装。
然后，我们需要全局安装 swagger-codegen。打开命令行工具，执行下面的命令：
npm install -g swagger-codegen
安装完成之后，使用以下命令生成 TypeScript 模型代码：
swagger-codegen generate -i http://petstore.swagger.io/v2/swagger.json -l typescript-fetch -o ./petstore-ts
上面的命令中，-i 指定接口文档 URL，-l 指定生成器类型，-o 指定输出目录，这里我们将输出到 ./petstore-ts 目录下。如果一切正常，我们会在 ./petstore-ts/models 目录下找到 Pet.ts、Order.ts、Tag.ts、Category.ts 等模型文件。
我们可以简要地看一下 Pet.ts 模型文件的内容：
-- -------------------- ---- ------- ------ --------- --- - ----- ------- ----------- --------- ------- ------- ------------ -------------- -------- ----------- ---------- -------------- - ------ ---- ------------- - ----------- - --------- - ------- ------ --------- -------- - ------ ------- -------- ------- - ------ --------- --- - ------ ------- -------- ------- -
我们可以看到，Pet.ts 导出了三个接口类型：Pet、PetStatusEnum 和 Category。Pet 是一个包含多个属性的接口类型，PetStatusEnum 是一个枚举类型，Category 是 Pet 中 category 属性的接口类型。这些类型的定义能够帮助我们更准确地使用各种 API。
然而，在实际的项目开发中，我们可能需要编写更多的 TypeScript 类来处理这些模型。手动编写这些类不仅繁琐，而且容易出错。幸运的是，swagger-model-generator-ts 可以帮助我们自动生成这些类，从而节省时间并减少错误。
使用 swagger-model-generator-ts 生成 TypeScript 类
首先，在项目根目录下执行下面的命令来安装 swagger-model-generator-ts:
npm install swagger-model-generator-ts --save-dev
安装完成后，我们就可以使用 swagger-model-generator-ts 来生成 TypeScript 类。我们需要先创建一个 TypeScript 文件，例如 petstore-model.ts：
-- -------------------- ---- -------
------ - --- - ---- ---------------
----- ------------- -
------- ----- ----
------ --- ------ --- -
------ ----------
-
------ --- -------- ---- -
--------- - ----
-
-
------ ------- --------------在这个文件中，我们创建了一个类 PetstoreModel，它有一个私有属性 _pet，以及两个公共属性 get pet 和 set pet，这些属性都是从 models/Pet 中引入的。
接下来，在命令行中执行下面的命令：
npx swagger-model-generator-ts -i http://petstore.swagger.io/v2/swagger.json -c ./swagger-options.json -o ./petstore-models
其中，-i 参数用于指定 Swagger 文档路径，-o 参数用于指定生成代码的输出目录。-c 指定的是配置文件。
我们可以看到，执行该命令后，./petstore-models 目录下会生成一些 TypeScript 文件。
现在，我们可以使用 PetstoreModel 类来处理 Petstore API 的响应数据。使用 promise 方式获取 petstore 中存储的宠物的数据：
-- -------------------- ---- -------
------ ------------- ---- -------------------
------ ----- ---- -------------
----- -------- - ---------------------------------
----- ------------- - --- ----------------
---------------------------
-------------- -- ----------------
---------- -- -
----------------- - -----
-------------------------------
--
------------ -- ----------------------在上面的代码中，我们使用了 PetstoreModel 类来处理 Petstore API 的响应数据。在 fetch 的返回数据中，我们可以直接将 JSON 数据传递给 set pet 并将其保存在 _pet 属性中。此后，我们就可以在代码其他位置使用 petstoreModel.pet 访问 Pet 类型的对象。
总结
本篇文章介绍了如何使用 swagger-model-generator-ts 工具，将 Swagger 文档中的模型代码生成为 TypeScript 类型。这一过程可以帮助您减少重复编写代码的工作量，同时提高代码质量。我们在使用浏览器调试过程中也可以使用 swagger-editor 工具方便的对 swagger 规范进行修改。
来源：JavaScript中文网 ，转载请注明来源 https://www.javascriptcn.com/post/600672593660cf7123b363a0