在开发前端类的应用时，我们经常需要使用 Web 开发框架来搭建服务端 API，而生成 API 文档则是一个不可避免的任务。在 Koa.js 这样的 Web 框架中，我们可以使用 Swagger 这个工具来方便地生成 API 文档并且提供 API 接口测试的功能。本文将详细介绍在 Koa.js 中使用 Swagger 进行API文档生成的步骤和指引，并提供相应的示例代码。
什么是 Swagger？
Swagger是一个流行的、开源的API文档规范和工具集，它提供了一种描述、生产、消费RESTful web服务的方式，可以帮助开发人员更好地了解API的使用方法，同时也可以辅助开发人员快速构建和测试API接口。Swagger提供的规范称为OpenAPI，它可以让我们专注于实现API逻辑而不是文档编写，提高API开发的效率。
在 Koa.js 中集成 Swagger
使用 Swagger 可以很容易地为你的 API 生成规范和文档，并且支持在浏览器中测试 API 接口。在 Koa.js 中，我们可以使用 swagger-jsdoc 和 swagger-ui-express 这两个库来实现集成。
Step 1: 安装依赖
现在开始，请先打开终端，在你的 Koa.js 项目中输入以下命令，安装 swagger-jsdoc 和 swagger-ui-express 两个库：
npm install swagger-jsdoc swagger-ui-express
Step 2: 编写 常规的 Swagger 文档
随着 Koa.js 项目成长，你会随着时间的推移，编写的代码会逐渐增加。如果不管理 API，代码会变得越来越难维护。这就是 Swagger 发挥作用的地方。
首先，我们需要编写 Swagger 规范，这里使用注释的形式来描述。在项目中新建一个 swagger.json 文件夹，我们在这个目录下面创建一个新的 swagger.yaml 文件，输入以下基本信息：
openapi: 3.0.0 info: version: 1.0.0 title: My API description: 'Description of my app' servers: - url: http://localhost:3000/api
其中，openapi 是规范版本，info 对象是 API 的基本信息，servers 表示 API 所在的服务器地址。
接下来，我们需要使用 swagger-jsdoc 来解析注释。在项目中新建一个名为 swagger.js 的文件：
-- -------------------- ---- -------
----- ------------ - -------------------------
----- ----------------- - --------------------------
----- ------- - -
------------------
----- -
----------------
---------------
--
--
----- ----------- - ----------------------
-------------- - ------------在上述代码中，我们通过传递文件路径指向路由和模型文件夹，告诉 Swagger 哪些文件需要解析放入文档中。注意，swaggerSpec 导出的内容在下一步中将需要用到。
Step 3: 集成Swagger UI
到此为止，Swagger 规范已经生成了，我们需要将其绑定到 Swagger UI 中。在项目中，我们可以使用 swagger-ui-express 中间件来将 Swagger 规范绑定到 UI 界面上。
在欲使用 Swagger 的 Koa.js 项目中的 app.js 中，进行如下配置：
const swaggerUi = require('swagger-ui-express');
const swaggerSpec = require('./swagger');
app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerSpec));现在，当你在浏览器中访问 http://localhost:3000/api-docs ，你会看到 Swagger UI 界面。默认情况下，文档中将会显示与 apis: ['./routes/*.js',' ./models/*.js'] 定义在Swagger.js 文件中的路径中的 Route、参数和响应信息的信息。
Step 4: 配置 Swagger 文档
以上，我们的 Koa.js 项目已经和 Swagger 集成完成。然而在 Swagger-UI 中，有很多高级配置可以用来优化接口测试的体验。例如，可以使用 Swagger 的 authorizations 或 securityDefinitions 去验证授权令牌，或者自定义 UI 主题等。
这些高级配置可以在 swagger.yaml 文件中定义，Swagger UI 将此视为可选配置。
securityDefinitions:
api_key:
type: apiKey
in: header
name: TokenAuthorization在代码中，我们将上面定义的 authorization 定义绑定到 options 对象中：
-- -------------------- ---- -------
----- ------- - -
------------------
----- -
----------------
---------------
--
-- ----------
-------------------- -
-------- -
----- ---------
----- ----------------
--- ---------
--
--
--现在，Swagger-UI 将在 UI 面板中提供一个输入字段，接口测试员可以在此输入授权令牌以进行 API 测试。
示例代码
首先，创建一个 Koa.js 项目，运行 npm init -y 自动创建 package.json 文件：
mkdir koa-swagger && cd koa-swagger npm init -y
然后，安装 Koa.js、swagger-jsdoc 和 swagger-ui-express：
npm install koa swagger-jsdoc swagger-ui-express
接下来，创建一个 index.js 文件，并在其中编写相应代码：
-- -------------------- ---- -------
----- --- - ---------------
----- ------ - ----------------------
----- --------- - ------------------------------
----- ----------- - ---------------------
----- --- - --- ------
----- ------ - --- ---------
--------------- ----- ----- -- -
---------- - ----
-------- - -
------- ----------
----- ------- -------
--
-------
---
------------- ----- ----- -- -
-------------------------------------- -----
--------
-------------------------------
-------- ----------------- ------------- -------
--
----- -------
---
------------------------------------------------------
-------------------- ---------------- ------------------------------
----- ---- - ---------------- -- -----
---------------- -- -- -
------------------- ------- -- ---- -----------
---现在，我们在项目的根目录中创建 swagger.js 文件，来定义Swagger规范，代码如下所示：
-- -------------------- ---- -------
----- ------------ - -------------------------
----- ------- - -
------------------ -
-------- --------
----- -
------ ---- ------- --- ---------------
-------- --------
------------ -- ------ ----
--
-------- -
-
---- ------------------------
------------ ------------ -------
-
-
--
----- ------------
--
----- ----------- - ----------------------
-------------- - ------------现在，所有的配置都已经好了，你可以使用 npm start 命令来启动 Koa.js 服务，并且在浏览器中访问 http://localhost:3000/api-docs ，来查看 Swagger UI 界面。
总结
本文介绍了如何在 Koa.js 中，通过使用 Swagger 工具来帮助我们快速地生成 API 文档并在浏览器中测试 API 接口。在实践中，你可以进一步学习如何自定义自己的 Swagger UI 界面，并且通过 Swagger 的 authorizations 或 securityDefinitions 配置项对授权令牌进行验证。通过使用 Swagger，我们能够大大提高 API 开发的效率，使我们的开发更加顺畅和高效。
来源：JavaScript中文网 ，转载请注明来源 https://www.javascriptcn.com/post/64643b19968c7c53b051c2aa