Expressdocs 是一个基于 Express.js 构建的文档生成工具。它可以生成美观的 API 文档，可根据注释自动生成文档，省去手动编写 API 文档的烦恼。在本篇文章中，我们将讲解如何使用 Expressdocs 来生成详细的 API 文档，并将包含示例代码。
安装
首先，我们需要通过 npm 安装 Expressdocs。使用以下命令：
npm install expressdocs --save-dev
安装完成后，在你的项目中引入 Expressdocs：
const expressDocs = require("expressdocs");
app.use(expressDocs.generate({
routes: "routes/*.js",
outputPath: "public/docs"
}));配置
在配置选项中，我们需要指定以下几个选项：
- routes：指向文档和路由的文件路径。这可以是单个文件、多个文件或一个目录。
- outputPath: 指定文档生成的输出路径。
在 package.json 文件中我们也需要添加以下配置：
"scripts": {
"docs": "expressdocs --config expressdocs.config.js"
},这样在命令行中执行 npm run docs 就会生成文档。
注释
在编写路由时，我们需要使用注释来告诉 Expressdocs 哪些信息应该出现在 API 文档中。
以下是几个常见的注释用法：
@desc: 描述 API 的作用。@url: 指定 API 的 URL。@method: 指定请求方法。@params: 指定 API 的参数。@returns: 描述响应的数据。
以下是一个简单的示例：
/**
* @desc user login
* @url /api/login
* @method POST
* @params {string} username - 用户名
* @params {string} password - 密码
* @returns {string} token - 用户 Token
*/
app.post("/api/login", function(req, res) {
// ...
});通过以上注释，Expressdocs 就可以自动将 API 的信息收集起来，生成一个美观的 API 文档。
示例代码
以下是完整的示例代码：
const express = require("express");
const expressDocs = require("expressdocs");
const app = express();
/**
* @desc user login
* @url /api/login
* @method POST
* @params {string} username - 用户名
* @params {string} password - 密码
* @returns {string} token - 用户 Token
*/
app.post("/api/login", function(req, res) {
// ...
});
app.use(expressDocs.generate({
routes: "routes/*.js",
outputPath: "public/docs"
}));
app.listen(3000, function() {
console.log("Server started...");
});在我们的项目中，我们会将所有路由存储在 routes 目录中。因此，我们将路由文件夹指定为 routes/*.js。在这个例子中，我们还指定了输出路径为 public/docs，并在 package.json 文件中设置了 npm run docs 命令来生成文档。
结论
在本文中，我们介绍了 Expressdocs 的安装和配置及注释用法，以及包含完整的示例代码。使用 Expressdocs，你可以快速地生成美观、详细的 API 文档，让你的接口更加易于使用和易于维护。希望本文对你有所帮助！
来源：JavaScript中文网 ，转载请注明来源 本文地址：https://www.javascriptcn.com/post/600673e3fb81d47349e53e21