在前端开发中，为 API 生成文档是一项必要的工作。手动编写 API 文档存在一定的繁琐性和易出错性，而自动化生成 API 文档则可以减少这些问题。在 Koa2 中，我们可以使用一些工具来自动生成 API 文档。
搭建 Koa2 项目
首先，我们需要搭建 Koa2 项目。可以使用 koa-generator 工具来生成 Koa2 项目的基本结构。在命令行中输入以下命令：
npm install -g koa-generator koa2 api-doc-generator cd api-doc-generator npm install
运行 npm start 启动项目，打开浏览器，输入地址 http://localhost:3000 即可看到项目的首页。
安装 swagger-jsdoc 和 swagger-ui-express
接下来，我们需要安装 swagger-jsdoc 和 swagger-ui-express，它们是生成 API 文档所必需的工具。在命令行中输入以下命令：
npm install --save swagger-jsdoc swagger-ui-express
配置 swagger-jsdoc
在项目的根目录下新建 swagger.json 文件，并配置 swagger-jsdoc。例如：
-- -------------------- ---- -------
-
-------------------- -
---------- --------
------- -
-------- ---- ---------------
---------- --------
-------------- ---- --------------
--
---------- -
-
------ -----------------------
-
-
--
------- -
---------------
-
-apis 字段是指定需要生成 API 文档的路由文件，这里指定了所有 routes 文件夹下的 .js 文件。更多配置可以参考 swagger-jsdoc 的官网。
配置 swagger-ui-express
在 Koa2 项目中，我们可以使用 swagger-ui-express 将 swagger 文档渲染成 web 页面。在 app.js 中添加以下代码：
const swaggerJSDoc = require('swagger-jsdoc');
const swaggerUi = require('swagger-ui-express');
const swaggerSpec = swaggerJSDoc(require('./swagger.json'));
app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerSpec));swaggerUi.serve 是指定所需要展示的文档，在页面中访问地址 http://localhost:3000/api-docs 即可看到 API 文档的界面。
添加 swagger 注释
将路由代码中的 ctx.body 修改成 ctx.body = {data: 'Hello World'};，并添加 swagger 注释：
-- -------------------- ---- ------- --- - -------- - -- - ---- - -------- --- ----- ----- - ------------ ------ ----- ----- - ---------- - ---- - ------------ ---------- -- --------------- ----- ----- ----- -- - -------- - ------ ------ -------- --- -------------- - -------
swagger 注释是声明路由的元数据，这些元数据将被 swagger-jsdoc 解析成一份 swagger 文档。
生成 API 文档
现在，我们已经完成了所有的配置。在命令行中输入以下命令即可生成 API 文档：
npm run doc
doc 是在 package.json 中配置的脚本，代码如下：
{
"scripts": {
"start": "node ./bin/www",
"doc": "node ./swagger.js"
}
}swagger.js 的代码如下：
const swaggerJSDoc = require('swagger-jsdoc');
const fs = require('fs');
const swaggerSpec = swaggerJSDoc(require('./swagger.json'));
fs.writeFileSync('./public/swagger.json', JSON.stringify(swaggerSpec, null, 2));执行完命令后，在项目根目录的 public 文件夹下会生成一个 swagger.json 文件，即我们生成的 API 文档。
总结
Koa2 如何自动生成 API 文档？我们已经学习了如何使用 swagger-jsdoc 和 swagger-ui-express 工具来生成 API 文档。这些工具可以快速生成文档，并且可以很方便地进行配置和使用。在实际开发中，我们可以根据自己的需求来定制 API 文档，提高开发效率和代码可读性。
来源：JavaScript中文网 ，转载请注明来源 https://www.javascriptcn.com/post/6544a3d77d4982a6ebe7c261