Koa2 如何自动生成 API 文档？-JavaScript中文网-JavaScript教程资源分享门户

在前端开发中，为 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。例如：

// javascriptcn.com 代码示例
{
  "swaggerDefinition": {
    "openapi": "3.0.0",
    "info": {
      "title": "API Documentation",
      "version": "1.0.0",
      "description": "API Documentation"
    },
    "servers": [
      {
        "url": "http://localhost:3000"
      }
    ]
  },
  "apis": [
    "./routes/*.js"
  ]
}

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 注释：

// javascriptcn.com 代码示例
/**
 * @swagger
 * /:
 *   get:
 *     summary: Get Hello World
 *     description: Return Hello World
 *     responses:
 *       200:
 *         description: Successful
 */
router.get('/', async (ctx, next) => {
  ctx.body = {data: 'Hello World'};
});

module.exports = router;

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