简介
typescript-swagger-tools 是一个 TypeScript 模块，它可以让你为 API 生成 Swagger 规范，并且能够为 TypeScript 生成与规范匹配的 API 客户端。在这篇文章中，我们将介绍如何使用 typescript-swagger-tools 来快速地构建一个基于 Swagger 规范的 API 客户端。
TypeScript 后端框架
Back-End 是应用程序的关键部分，它是负责处理来自前端的请求的代码。现在，有很多后端框架可供开发人员使用，比如 Node.js, Django 和 Ruby on Rails。我们将在本文中使用 TypeScript 后端框架 Express.js 作为我们的开发环境。
首先，我们需要安装 typescript-swagger-tools：
npm install --save typescript-swagger-tools
接下来，我们将逐步打造一个能够使用 Swagger 规范与 API 交互的 TypeScript 客户端。
生成 Swagger 规范
Swagger 规范提供了一种描述 API 的规范方法，并且可以通过 Swagger UI 进行可视化操作。下面是一个简单的 swagger.yaml 文件：
-- -------------------- ---- -------
-------- -----
-----
-------- -----
------ -- ---
--------- -------
-----
- ----- -----
------------ ---- ----------
------
-------
-----
-----
- -----
-------- ------ - ----
------------ ----------
---------
- ----------------
-----------
- --- ----
----- ----
------------ --- ---- -- ------
--------- ----
-------
----- --------------------
----------
------
------------ ------- ---- ------
-------
----- --------------------
------------
-----
----- ------
---------
- --------
-----------
---------
----- ------
在上面的 YAML 文件中，我们定义了一个名为 users 的标签，表示这个 API 的操作是有关用户的。我们还定义了一个名为 /users 的路径，并使它支持 POST 操作 createUser，它接收一个用户对象作为参数。我们使用对象的 schema 属性来描述这个用户对象，它在 Swagger 规范中定义。
但是，我们不想手动编写 YAML 文件，那么有没有更好的方法呢？ Swagger 官方提供了一种称为 "annotations" 的方法，可以在我们的代码中直接编写 Swagger 规范。
我们可以通过添加 @swagger 注释在我们的 TypeScript 代码中描述我们的 API。下面是一个使用 @swagger 注释实现 Swagger 规范描述的 TypeScript 代码。
-- -------------------- ---- ------- ------ - -- ------- ---- ---------- ------ - -------- -------- - ---- ---------- ------ - ----------- - ---- ---------- ----- ---- ----------- - ---------- ------------------------ --- - -------- - ------------ - ----- - --------- - - ---- - ----------- - ----- - ----- ------ - - ------- - ----- - ----- - - ----- - ------------ ------- - --- ---- - --------- - - ---------------- - ----------- - - ----- ---- - ------------ ---- ------ - --- ---- - --------- ---- - ------- - ----- -------------------- - ---------- - ---- - ------------ ---- ------- -- ------------------------- ----- -------- ---- --------- -- - ----- ---- - -------------- --------------------- ---- ---------- -- ---------- --------------- --- ---------------- -- -- - ------------------- ----------- ---
在上面的代码中，我们使用 @swagger 注释来定义了一个 User 等模型，并使用 /users 路径和 POST 方法定义了一个 "createUser" 操作。
现在的问题是，如何从我们的 TypeScript 代码生成 swagger.yaml 文件呢？很简单，我们只需要运行命令：
npx ts-node your-file.ts -o path/to/your/swagger.yaml
这个命令将把你的 TypeScript 文件 your-file.ts 解析为 Swagger 规范并保存到 path/to/your/swagger.yaml 文件中。
生成 API 客户端
现在我们已经生成了用于API的 swagger.yaml 文件，接下来我们需要一个可以快速生成 TypeScript 客户端的工具。typescript-swagger-tools 就是做这件事的。它能够读取我们的 swagger.yaml 文件并生成符合 Swagger 规范的 TypeScript 客户端。
npm install --save typescript-fetch-api
下面是一个简单使用 typescript-fetch-API 的 TypeScript 客户端生成文件的示例代码：
-- -------------------- ---- -------
------ - ------------ ---------- ------------- - ---- ---------------------------
----- -------------- - ----------------------- -- -----------------------
----- ---------- --------- - -
------- --------
----- ------------------
--------- ------
-------- ---
---------------- ---
--
----- -------------- ------------- - -
------- -
----- ---------------
--
--
------ -- -- -
----- --- - ----- ---------------------- ---------------
-----------------------
-------------------------------------- ----- ---------
-----在上面的代码中，我们首先导入 generateApi 和 SwaggerConfig。然后我们设置了我们的 schemaFilePath 和 apiConfig，它表示了我们 API 的基本配置，比如协议，主机，请求头等等。
最后，我们使用 generateApi 函数并且传递我们的 apiConfig 和 swaggerConfig 作为参数来生成 TypeScript API 客户端。我们可以通过访问 api.users 属性来获取我们的 User API，可以像下面这样使用 createUser 方法：
api.users.createUser({ name: "Test User" });总结
本文介绍了 TypeScript 后端框架和 typescript-swagger-tools 如何快速构建符合 Swagger 规范的 API 客户端。我们了解了生成 Swagger 规范的 YAML 文件，以及如何使用 typescript-swagger-tools 生成 TypeScript API 客户端。这提供了一种快速编写可靠和可重复使用的代码的方法，可以用于创建许多不同的应用程序。
希望能够通过这篇文章帮助大家更好地了解 TypeScript 开发及使用 typescript-swagger-tools 工具快速构建符合 Swagger 规范的 API 客户端的方法。
来源：JavaScript中文网 ，转载请注明来源 https://www.javascriptcn.com/post/6005547c81e8991b448d1c24