Swagger UI 是一个流行的 API 文档工具，它提供了一个易于使用的界面来查看和测试 API 接口。在前端开发中，我们通常需要与后端开发者协作开发 API 接口，因此使用 Swagger UI 可以让我们更加顺畅地进行合作。
Koa.js 是一个轻量级的 Node.js 框架，它提供了一种简单的方式来构建 Web 应用程序和 API。在本文中，我们将会探讨如何使用 Swagger UI 和 Koa.js 来查看和测试 API 接口。
准备工作
在开始之前，我们需要准备一些工作。我们将创建一个简单的 Koa.js 应用程序，其中包含一个 API 接口。我们使用 Node.js 和 npm 来构建应用程序。如果您还没有安装这些工具，请先安装它们。
接下来，我们需要安装一些依赖包：
npm install koa koa-router swagger-jsdoc swagger-ui-koa -S
这里我们安装了 Koa.js、Koa 路由、Swagger-jsdoc 和 Swagger-ui-koa。
接着，我们需要创建一个 Koa.js 应用程序，并设置路由。我们创建一个 app.js 文件，并添加以下代码：
-- -------------------- ---- -------
----- --- - ---------------
----- ------ - ----------------------
----- --- - --- ------
----- ------ - --- ---------
------------------------ ----- ----- ----- -- -
-------- - -
------ -
- ----- ------ --
- ----- ------ -
-
--
---
------------------------------------------------------
---------------- -- -- ------------------- -- ------- -- -------------------------这个应用程序中，我们创建了一个 /api/users 的路由，它将返回一个包含两个用户对象的 JSON。
使用 Swagger-jsdoc 生成 API 文档
现在，我们已经定义了一个简单的 API 接口。接下来，我们将使用 Swagger-jsdoc 生成 API 文档，Swagger-ui-koa 则提供了一个可视化的 Swagger UI 界面与文档结合展示。我们需要做的只是在代码中添加注释。
首先，我们需要在应用程序中引入 swagger-jsdoc 和 swagger-ui-koa：
const swaggerJSDoc = require('swagger-jsdoc');
const koaSwagger = require('swagger-ui-koa');然后，我们将在代码中添加 Swagger-jsdoc 的注释，以告诉 Swagger-jsdoc 如何为 API 生成文档。我们可以使用类似 JSDoc 的注释格式：
-- -------------------- ---- -------
---
- --------
- -----
- - ----- ----
- ------------ ---- ---
-
- ------------
- -----
- ----- ------
- -----------
- -----
- ----- ------
-
- -----------
- ----
- -----
- - ----
- -------- --- --- -----
- ---------
- - ----------------
- ----------
- ----
- ------------ ---------- ---------
- -------
- ----- -----
- ------
- ----- --------------------
--
------------------------ ----- ----- ----- -- -
-------- - -
------ -
- ----- ------ --
- ----- ------ -
-
--
---这个注释中，我们定义了一个名为 user 的标签，接下来定义了一个名为 User 的对象，其中包含一个 name 属性。最后，我们定义了一个关于 /api/users 的路由，它将返回一个包含两个用户对象的 JSON。
接下来，我们需要使用 swaggerJSDoc 来生成 Swagger 文档和路由：
-- -------------------- ---- -------
----- ------------- - -
------------------ -
----- -
------ ------- -----
-------- --------
------------ -------------- -- ------- ---- -------
-
--
----- ------------
--
----- ----------- - ----------------------------
--------------------
------------ -----------
--------------- -
----- ------------
-
----这个代码中，我们使用 swaggerConfig 定义了 Swagger 的相关配置。它包含了一些基本的信息，例如 API 的标题、版本和描述。我们还指定了 apis，它定义了要从哪些文件中提取 Swagger 注释。
使用 swaggerJSDoc 函数会返回一个 Swagger 规范对象 swaggerSpec，它是基于注释自动生成的 Swagger 文档。最后，我们使用 koaSwagger 中间件来将 Swagger UI 和 Swagger 文档结合展示。其中，我们设置了 routePrefix 为 /swagger，即在浏览器中的访问路由为 http://localhost:3000/swagger。
现在，我们已经完成了使用 Swagger-jsdoc 生成 API 文档的工作。
查看和测试 API 接口
启动 Koa.js 应用程序 node app.js，然后打开浏览器，访问 http://localhost:3000/swagger。
就可以看到如下的 Swagger UI 界面：
在 Swagger UI 界面中，可以看到通过注释自动生成的文档，其中包含了 /api/users 接口的信息。
点击 /api/users，Swagger UI 将会展示此接口的详细信息：
在 Swagger UI 中，我们不仅可以查看接口的详细信息，还可以使用 Swagger UI 提供的测试工具测试接口。例如我们可以点击右侧的“Try it out”按钮：
在弹出的对话框中，我们可以看到此接口的请求信息，例如请求的 URL、请求方式和请求头。我们还可以设置请求的参数。
随着我们对 Swagger UI 的深入学习和了解，我们可以更加方便地协作工作，并可以更加容易地编写文档和测试代码。同时，Swagger UI 还提供了许多其他的功能，例如提供接口的 mock 数据，帮助我们更好地调试和开发接口。
总结
本文介绍了如何使用 Swagger UI 和 Koa.js 查看和测试 API 接口。我们了解了如何使用 Swagger-jsdoc 自动生成 API 文档，并看到了 Swagger UI 提供的便利性。通过本文的学习，我们应该可以更加方便地协作工作，并更加方便地编写文档和测试代码。
来源：JavaScript中文网 ，转载请注明来源 https://www.javascriptcn.com/post/64cb2d855ad90b6d041f1ea1