nodejs自动生成接口文档_使用 apiDoc 为你的Node.js API 生成文档

当你为其他开发人员(前端，桌面，移动等)开发 API 时，需要生成一份风格良好的文档，以便他们知道可以使用的内容和方式，这非常重要。

为此，在Node.js项目中，我一直在使用apiDoc，因为它能够从源代码中的注释生成HTML文档。

对于本文，我将使用我开发的 TODO List API 作为示例。你可以从这里克隆或下载它。

路由和注释

在我关于使用 mocha 进行测试并使用 istanbul 进行代码覆盖测试的文章中，我在 TODO List API 中显示了 Task 端点的示例：

import Task from "../controllers/tasks";

export = (app) => {

const endpoint = process.env.API_BASE + "tasks";

app.post(endpoint, Task.create);

app.delete(endpoint + "/:id", Task.delete);

app.get(endpoint + "/:id", Task.getOne);

app.get(endpoint, Task.getAll);

app.put(endpoint + "/:id", Task.update);

};

这代表了与系统中任务相关的所有端点。我们怎样才能使用它们呢？使用 API ​​的开发人员应该向每个端点发送什么数据呢？

到现在为止，他们除了去查看代码之外没有其他方法可以搞清楚，但是这些代码不应该被用作这个目的。

有了 apiDoc，我们可以用注释来生成文档。我的方法是在 routes 目录下的文件中配置的每个端点的前面编写它们。当我提到如何配置和组织我的 Node.js 项目时，如果你不确定我在说什么请 点击这里。

使用注释，我们的任务端点(内部routes/tasks.ts)将如下所示：

import Task from "../controllers/tasks";

export = (app) => {

const endpoint = process.env.API_BASE + "tasks";

/*** @api {post} /api/v1/tasks Create a task* @apiVersion 1.0.0* @apiName Create* @apiGroup Task* @apiPermission authenticated user** @apiParam (Request body) {String} name The task name** @apiExample {js} Example usage:* const data = {* "name": "Do the dishes"* }** $http.defaults.headers.common