后端问：作为前端如何实现自动生成接口文档

前言，众所周知，后端的接口文档一般使用 swagger/openapi，而其他的一般接口文档也基本是使用 openapi 来进行解析的。例如 redoc(20.8k star) 和 knife4j(3.5k star) 等.

作为一个通用的解决方案，前端社区自然也有对应的实现。

如何实现 swagger 文档界面

swagger-ui-express 是一个 express 插件，可以在 express 中实现 swagger-ui。然后传入 openapi 来渲染接口文档。

const express = require("express");
const app = express();
const swaggerUi = require("swagger-ui-express");
const swaggerDocument = require("./swagger.json");

var options = {
  explorer: true,
};

app.use(
  "/api-docs",
  swaggerUi.serve,
  swaggerUi.setup(swaggerDocument, options)
);

从上面的示例可以看到 swagger.json 即为接口文档的描述数据。在这种情况下我们需要准备已经有的 json 数据方可显示文档。

如何生成文档描述数据

我们可以安排 swagger-jsdoc 这个库，来实现在代码中写接口注释，即可生成文档数据。

// Initialize swagger-jsdoc -> returns validated swagger spec in json format
const swaggerSpec = swaggerJSDoc(options);

app.use("/api-docs", swaggerUi.serve, swaggerUi.setup(swaggerSpec));

注释示例：

/** * @openapi * /: * get: * description: Welcome to swagger-jsdoc! * responses: * 200: * description: Returns a mysterious string. */
app.get("/", (req, res) => {
  res.send("Hello World!");
});

文档不想写，注释不想写，就想生成接口文档

在之前的示例中，虽然我们可以通过写 jsdoc 形式的注释来实现也写接口文档。但问题是，我都能在注释里把文档写清楚了，就不叫“生成文档”了，而叫收集文档片段，而且在代码里写文档，似乎也不太优雅。

要实现注释写不想写，就能实现接口文档的生成，我们首先要让某个工具能理解我们代码的意图。如何理解？

• 方法 1 通过人工智能去理解代码意图然后生成文档
• 方法 2 通过代码钩子或埋点获取意图生成文档

很显然，方法 1 不在我们的实现范畴，因为它涉及大模型、数据安全、本地化等各种问题。而方法 2 则是我们能去研究的方案，例如我们使用 vue 开发项目时，vue-devtool 插件就能看到 vue 相关的状态，这就是在 vue 的实现中有为插件开放获取状态的接口。如果没有开放，也可以通过拦截、代理等方法获取运行状态。

分析接口意图

对于原生的 express 产生的接口，我们可以通过 app.routes app._router.stack express.Router() router.stack 等 api 获取到当前所使用的接口。但我们这里使用 mockm，接口是直接声明在对象中的，就更简单了许多。

api: {
  "/a": 111,
  "/b": 222,
  'get /name': `张三`,
  '/status/:code' (req, res) {
    res.json({statusCode: req.params.code})
  },
},

观察上面的 api 对象，例如 "/a": 111 实现的接口是无论通过什么方法请求 /a 这个接口，都返回数字 111，而 'get /name': '张三', 则是通过 get 请求 /name 时返回字符串 张三。

以下是转换 api 为 openApi json 的实现：

toOpenApi(serverRouterList) {
  const mapObj = {
    all(item) {
      return [
        `delete`,
        `get`,
        `patch`,
        `post`,
        `put`,
      ].map(method => {
        return {
          ...item,
          method,
          tags: item.tags || [`all-method`],
        }
      })
    },
  }
  serverRouterList = serverRouterList.map(item => {
    const fn = mapObj[item.method]
    return fn ? fn(item) : [item]
  }).flat()
  return serverRouterList
}

serverRouterList 是格式化 api 后面的数据，包含 method route action alias 等，其中要生成接口文档，只需要有 method route 就足够了。

一个只包含此接口的 openApi json 生成后如下：

{
  "openapi": "3.0.0",
  "servers": [
    {
      "url": "/"
    }
  ],
  "tags": [],
  "paths": {
    "/a": {
      "get": {
        "parameters": [],
        "responses": {}
      }
    }
  }
}

看起来是简单吧？

然后把它交给 swagger-ui 即可渲染出文档，展现和使用都没有问题：

如何为接口分组、添加字段说明、数据验证等功能？

接口分组比较简单，直接为接口设置标签就行。由于在 mockm 中可以直接写字面量即可生成 api，但我们要为 api 添加额外说明的时候，就不能简单的使用字面量了。

为了兼容 mockm 的已有实现，我们扩展一个叫 side 的函数，用于收集额外信息和返回字面量。

"post /api/login": side({
  tags: [`admin`],
  summary: `根据用户名获取 token`,
  schema: {
    body: joi.object({
      username: joi.string()
        .default(`李蕾`)
        .required()
        .description(`用户名`),
    }).description(`用户信息`),
  },
  action (req, res) {
    const { username } = req.body
    res.json({
      status: 200,
      message: `欢迎 ${username}, 登录成功`,
      token: `tokentoken`,
    });
  }
}),

可以看到，我们在 side 函数中，为 api 进行了分组，并且为 api 添加了描述，然后为 api 的每个字段添加了说明，是否必填，数字类型是什么等。

这时候可能有一个疑问，在前面提到了使用注释编写接口文档信息，而这里则是使用代码编写接口信息，他们之前的区别在哪里？

• 区别 1 使用注释编写时没有语法提示、代码完成、代码高亮等功能，十分不方便
• 区别 2 使用注释编写时，实际上是在写原始 openapi yaml 格式的数据，这要求你对 openapi 规范有相当的了解和熟悉
• 区别 3 使用代码编写时，顺便可以完成业务上的其他功能，而注释和业务是割裂的，我们都知道业务更新但注释没更新的那种噩梦

观察上面的代码，我们使用 joi 来进行数据描述，与此同时 joi 也可以为我们实现数据的校验。

以下是文档生成效果，可以看到数据描述、默认值(示例值)、类型、是否必填等都可以正常显示：

以下是接口校验功能的效果，我们在接口中声明了 username 为 string，但我们尝试传入数字 111，结果按预期运行，自动提示了哪个字段错误了，为什么错：

功能插件化

对于使用 mockm 的群体中，有一些朋友可能并不想去真的用它来实现 api ，更别说还要为 api 生成文档，所以把此功能抽离为插件，当有一天 mockm 的功能繁复时，可以拆分为插件包单独在其他仓库进行维护：

module.exports = async (util) => {
  const joi = await util.tool.generate.initPackge(`joi`);

  return {
    plugin: [util.plugin.validate, util.plugin.apiDoc],
  };
};

游乐场

安装和初始化 mockm

yarn add mockm
npx mm --config

编写接口

在 mm.config.js 中录入以下信息

module.exports = async (util) => {
  const joi = await util.tool.generate.initPackge(`joi`);

  return {
    plugin: [util.plugin.validate, util.plugin.apiDoc],
    api: {
      "post /api/login": util.side({
        tags: [`admin`],
        summary: `根据用户名获取 token`,
        schema: {
          body: joi
            .object({
              username: joi
                .string()
                .default(`李蕾`)
                .required()
                .description(`用户名`),
            })
            .description(`用户信息`),
        },
        async action(req, res) {
          const { username } = req.body;
          res.json({
            status: 200,
            message: `欢迎 ${username}, 登录成功`,
            token: `tokentoken`,
          });
        },
      }),
    },
  };
};

查看接口文档

浏览器打开 http://127.0.0.1:9000/doc 即可

一个基于 express 的框架。它可以快速生成 api 以及创造数据，开箱即用，便于部署。

github 地址：github.com/wll8/mockm，求 star 。