使用 apiDoc 为你的Node.js API 生成文档
翻译: 疯狂的技术宅
原文:jonathas.com/documenting…
未经许可,禁止转载!
当你为其他开发人员(前端,桌面,移动等)开发 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["Authorization"] = token;* $http.post(url, data)* .success((res, status) => doSomethingHere())* .error((err, status) => doSomethingHere());** @apiSuccess (Success 201) {String} message Task saved successfully!* @apiSuccess (Success 201) {String} id The campaign id** @apiSuccessExample {json} Success response:* HTTPS 201 OK* {* "message": "Task saved successfully!",* "id": "57e903941ca43a5f0805ba5a"* }** @apiUse UnauthorizedError*/app.post(endpoint, Task.create);/*** @api {delete} /api/v1/tasks/:id Delete a task* @apiVersion 1.0.0* @apiName Delete* @apiGroup Task* @apiPermission authenticated user** @apiParam {String} id The task id** @apiExample {js} Example usage:* $http.defaults.headers.common["Authorization"] = token;* $http.delete(url)* .success((res, status) => doSomethingHere())* .error((err, status) => doSomethingHere());** @apiSuccess {String} message Task deleted successfully!** @apiSuccessExample {json} Success response:* HTTPS 200 OK* {* "message": "Task deleted successfully!"* }** @apiUse UnauthorizedError*/app.delete(endpoint + "/:id", Task.delete);/*** @api {get} /api/v1/tasks/:id Retrieve a task* @apiVersion 1.0.0* @apiName GetOne* @apiGroup Task* @apiPermission authenticated user** @apiParam {String} id The task id** @apiExample {js} Example usage:* $http.defaults.headers.common["Authorization"] = token;* $http.get(url)* .success((res, status) => doSomethingHere())* .error((err, status) => doSomethingHere());** @apiSuccess {String} _id The task id* @apiSuccess {String} name The task name** @apiSuccessExample {json} Success response:* HTTPS 200 OK* {* "_id": "57e8e94ea06a0c473bac50cc",* "name": "Do the disehs",* "__v": 0* }** @apiUse UnauthorizedError*/app.get(endpoint + "/:id", Task.getOne);/*** @api {get} /api/v1/tasks Retrieve all tasks* @apiVersion 1.0.0* @apiName GetAll* @apiGroup Task* @apiPermission authenticated user** @apiExample {js} Example usage:* $http.defaults.headers.common["Authorization"] = token;* $http.get(url)* .success((res, status) => doSomethingHere())* .error((err, status) => doSomethingHere());** @apiSuccess {String} _id The task id* @apiSuccess {String} name The task name** @apiSuccessExample {json} Success response:* HTTPS 200 OK* [{* "_id": "57e8e94ea06a0c473bac50cc",* "name": "Do the disehs"* },* {* "_id": "57e903941ca43a5f0805ba5a",* "name": "Take out the trash"* }]** @apiUse UnauthorizedError*/app.get(endpoint, Task.getAll);/*** @api {put} /api/v1/tasks/:id Update a task* @apiVersion 1.0.0* @apiName Update* @apiGroup Task* @apiPermission authenticated user** @apiParam {String} id The task id** @apiParam (Request body) {String} name The task name** @apiExample {js} Example usage:* const data = {* "name": "Run in the park"* }** $http.defaults.headers.common["Authorization"] = token;* $http.put(url, data)* .success((res, status) => doSomethingHere())* .error((err, status) => doSomethingHere());** @apiSuccess {String} message Task updated successfully!** @apiSuccessExample {json} Success response:* HTTPS 200 OK* {* "message": "Task updated successfully!"* }** @apiUse UnauthorizedError*/app.put(endpoint + "/:id", Task.update);};
复制代码
如你所见,我们有 HTTP 方法的类型(post,put,get,delete)、端点地址、api 版本、它需要的权限类型、它需要的参数,还有如果用户是未经授权的应该返回怎样的响应和错误。
在官方网站中,你可以查看注释文档和可用参数。
那么这个 UnauthorizedError 来自哪里呢?
apiDoc 设置
有一些设置可以用 apiDoc 完成,这个 UnauthorizedError 就是我经常要用到的。
在 routes 目录中创建一个名为 __apidoc.js
的文件,其中包含以下内容:
// -----------------------------------------------------------
// General apiDoc documentation blocks and old history blocks.
// -----------------------------------------------------------// -----------------------------------------------------------
// Current Success.
// -----------------------------------------------------------// -----------------------------------------------------------
// Current Errors.
// -----------------------------------------------------------// -----------------------------------------------------------
// Current Permissions.
// -----------------------------------------------------------
/*** @apiDefine UnauthorizedError* @apiVersion 1.0.0** @apiError Unauthorized Only authenticated users can access the endpoint.** @apiErrorExample Unauthorized response:* HTTP 401 Unauthorized* {* "message": "Invalid credentials"* }*/// -----------------------------------------------------------
// History.
// -----------------------------------------------------------
复制代码
我还创建了另一个文件,也在 routes 目录中,名为 apidoc.json
该文件包含以下内容(示例):
{"name": "Test API - This is my API","version": "1.0.0","description": "This is my very powerful API","title": "Test API - This is my API","url": "https://testapi.com"
}
复制代码
生成文档时,apiDoc 将会使用这两个文件。
生成文档
在为每个端点编写注释并配置好项目之后,我们需要配置一个任务来生成文档。
我用 gulp 来做到这一切。安装所需的依赖项:
npm i gulp gulp-apidoc --save-dev
复制代码
然后在项目的根目录中创建一个名为 gulpfile.js
的文件。如果它已经存在,只需添加与 apiDoc 相关的部分:
const gulp = require("gulp");
const apidoc = require("gulp-apidoc");gulp.task("apidoc", (done) => {apidoc({src: "./routes",dest: "../docs/apidoc"}, done);
});gulp.task("watch", () => {gulp.watch(["./routes/**"], ["apidoc"]);
});
复制代码
你可以将那里的 “dest” 目录更改为另一个更适合你的目录。这就是你希望生成输出的位置。
现在你需要做的就是运行:
gulp apidoc
复制代码
之后,你只需要在上面 “dest” 中配置的目录中打开 index.html 文件,就会看到类似这样的内容):
其他开发人员也可以用 gulp 生成相同的内容,或者你甚至可以通过 Nginx 为生成的目录提供Web服务。
总结
在这本文中,我们了解了如何使用注释来记录 API,并使用 apiDoc 为它们生成 HTML 格式的文档。
你是否还用了其他软件来为你的 API 生成文档,或者你是否以其他方式使用 apiDoc?请在下面评论中留言讨论!
欢迎关注前端公众号:前端先锋,获取前端工程化实用工具包。
转载于:https://juejin.im/post/5cef97cff265da1bc14b0d3e
使用 apiDoc 为你的Node.js API 生成文档相关推荐
- Node.js API参考文档(目录)
Node.js v11.5.0 API参考文档 Node.js®是基于Chrome的V8 JavaScript引擎构建的JavaScript运行时. 关于文档 用法和示例 断言测试 稳定性:2 - 稳 ...
- Matlab联合wps的API生成文档,让API自动生成文档
原标题:让API自动生成文档 程序员最苦恼的事情莫过于写文档.由于业务口径频繁变更,因此很多接口也会频繁变更,频繁变更导致文档的维护是一件相当费时的事情,当优先级更高的事情袭来,更新文档反到成了次要工 ...
- node.js api接口_如何在Node.js API客户端中正常处理故障
node.js api接口 by Roger Jin 罗杰·金(Roger Jin) 如何在Node.js API客户端中正常处理故障 (How to gracefully handle failur ...
- 如何使用async / await和Firebase数据库编写漂亮的Node.js API
by Paul Breslin 保罗·布雷斯林(Paul Breslin) 如何使用async / await和Firebase数据库编写漂亮的Node.js API (How to write ...
- Puppeteer -headless Chrome 的 Node.js API
Puppeteer 是一个控制 headless Chrome 的 Node.js API .它是一个 Node.js 库,通过 DevTools 协议提供了一个高级的 API 来控制 headles ...
- nodejs 牛b,,,通过npm,数以万计的模块,Node.app:用Node.js API开发iOS“原生”应用
Node.app能够为应用程序提供兼容Node.js的JavaScript API,不仅占用资源非常少,而且还允许最大限度的代码重用和快速创新. 主要特性: 最大限度的代码重用:在iOS应用开发过程中 ...
- Web3.js API 中文文档
Web3.js API 中文文档 http://web3.tryblockchain.org/Web3.js-api-refrence.html web3对象提供了所有方法. 示例: //初始化过程 ...
- 以太坊智能合约开发,Web3.js API 中文文档 ethereum web3.js入门说明
以太坊智能合约开发,Web3.js API 中文文档 ethereum web3.js入门说明 为了让你的Ðapp运行上以太坊,一种选择是使用web3.js library提供的web3.对象.底层实 ...
- 使用apidoc生成文档
apidoc是通过在方法上的注释生成文档,不基于任何框架,对代码没有侵入性,只需要写好相关的注释即可,并且它仅通过写简单的配置就可以生成高颜值的api接口页面. 准备工作 apidoc基于node.j ...
最新文章
- 大数据-spark-hbase-hive等学习视频资料
- 将带下划线的字符串转换成大写(下划线后大写)的高效方法
- 实习随记-不定时更新
- 全世界还有44亿人无法上网
- 把图片保存到数据库的实现
- 微软开放Holographic平台,意在统一VR的操作系统?
- vb.net读取excel并写入dgv_读取PDF中的表格写入EXCEL?30行代码搞定
- Smarty模板技术学习(二)
- UpdatePanel的内容中出现自定义多语言运行异常
- WakaTime 记录你的时间(Moana 自动同步信息客户端)
- 计算机病毒实践汇总六:IDA Pro基础
- 一.Nginx的特性和一些知识点
- 根据当前节点获取所有上层结构的组织(递归算法)
- linux备份mysql数据库
- 广西搬迁贫困人口近70万 “土瑶”深度贫困地区脱贫显成效
- npm ERR! This is probably not a problem with npm. There is likely additional logging output above.
- ReactOS LiveUSB
- 微型计算机开不了机,联想C225微型计算机怎么开不起机呢?
- initramfs/initrd
- Linux运维-服务器系统篇
热门文章
- POJ 2054 Color a Tree (贪心)
- Python笔记(十五)_异常处理
- 使用sphinx快速为你python注释生成API文档
- PHP常用字符串函数小结
- react-native 打包apk 并解决 图片 不出现问题
- HDU3183 A Magic Lamp —— 贪心(单调队列优化)/ RMQ / 线段树
- 23种设计模式之简单工厂
- 函数04 - 零基础入门学习C语言35
- 使用c#操作IBM WebSphere MQ
- android 图片识别白色区域进行裁剪_【研途技能贴】| 4款好用的图片处理软件推荐...