在开发前端应用时，我们常常需要使用一些第三方的库和框架来方便我们的开发。其中，Swagger 是一款用于 API 文档和测试的开源工具，而 @types/swagger-ui-express 则是一款用于在 Express 应用中集成 Swagger UI 的 TypeScript 类型定义。
本文将介绍 npm 包 @types/swagger-ui-express 的使用教程，内容详细且有深度和学习以及指导意义。
安装
首先，我们需要安装 @types/swagger-ui-express 包。在终端中，输入以下命令：
npm install --save-dev @types/swagger-ui-express
这将会将包添加到你的 package.json 文件中。同时，@types/swagger-ui-express 也依赖于 Express 和 swagger-ui-express 包，因此我们也需要安装它们：
npm install --save express swagger-ui-express
配置
在完成安装后，我们需要在 Express 应用程序中配置 @types/swagger-ui-express。在你的应用程序入口文件中，添加以下代码：
-- -------------------- ---- ------- ------ ------- ---- ---------- ------ --------- ---- --------------------- ------ - -- --------------- ---- --------------------- ----- --- - ---------- ----- ---- - ---------------- -- ----- -------------------- ---------------- ---------------------------------- ---------------- -- -- ------------------- ------- -- ---- -----------
以上代码做了如下几件事情：
- 导入 express 和 swagger-ui-express 两个包；
- 导入 JSON 格式的 Swagger 文档文件（文件路径根据你的实际情况而定）；
- 初始化一个 Express 实例，指定端口号；
- 在 Express 实例中，使用 swaggerUi.serve 和 swaggerUi.setup 方法来集成 Swagger UI，并指定 Swagger 文档的地址为 /api-docs。
使用
完成上一步的配置后，我们就可以访问 http://localhost:8080/api-docs 来查看 Swagger UI 页面了。在该页面中，我们可以查看当前 Express 应用程序的 API 文档，并通过控制台测试这些 API。
同时，我们也可以在代码中使用 swagger-ui-express 提供的功能来生成和修改 Swagger 文档。以下是一个简单的示例，通过在路由器上使用 swaggerDocument.api 中的定义来创建一个新的路由：
-- -------------------- ---- -------
------ - ------ - ---- ----------
------ --------------- ---- ---------------------
----- ------ - ---------
------------------------- ----- ---- -- -
-- ----
---------- -------- ---- ----- --------- ---
---
----------------------------------- - -
----- -
------------ -------- - --- -------
----------- -
-
----- ----------
--- -------
------------ ---- ----- ------
--------- -----
------- -
----- ---------
----------- -
----- - ----- -------- --
------------ - ----- -------- -
-
-
-
-
-
--
------ ------- -------以上代码中，我们在 swaggerDocument.paths 对象中添加了一个新的路由路径及其相关的参数和描述信息，以便在 Swagger UI 中显示。
总结
通过本文，我们了解了如何使用 npm 包 @types/swagger-ui-express 来集成 Swagger UI 到 Express 应用程序中，并在代码中生成和修改 Swagger 文档。
在现代 Web 应用程序的开发中，API 文档的编写和维护对于开发者而言变得越来越重要。因此，了解如何使用 Swagger 和相关工具来更好地管理和测试 API 文档，将会使我们的工作变得更加轻松和高效。
来源：JavaScript中文网 ，转载请注明来源 https://www.javascriptcn.com/post/202326