NodeJS Restful的api文档
文章目录
一.前言
目前前后端分离的模式,已经深得各大公司的喜爱,然而前后端沟通的成本就增加了,我们的书面文档就成了关键,想想,我们在开发的时候,直接把文档丢给相应的调用接口的人,不管是前端后端,都开心了.按照接口文档的规范去开发,效率会提高很多.
之前我做.net开发的时候,就是用的swagger直接生成文档,还可以在线调试.但是呢有些公司开发的模式各有不同:比如开发的时候,前端不可能一直等着后端把功能模块都搞定之后再生成文档,毕竟是协同开发,所以有的时候,是先有文档,再有接口,不过这种模式,一般是需要功底比较深的开发人员,可以在开发前期就直接定出所有的文档.我们这边呢,今天不说swagger,虽然swagger也可以搭配nodejs生成接口文档,但是我这介绍的是:ApiDoc框架直接生成的api文档.
二.接口文档
一个规范的接口包含以下内容
- 请求方式
- 请求地址
- 请求参数
- 后端响应4
三.Apidoc生成文档
1. 全局安装
$ npm install apidoc -g
2.项目根目录配置apidoc.json
{
"name": "example",
"version": "0.1.0",
"description": "apiDoc basic example",
"title": "Custom apiDoc browser title",
"url" : "https://api.github.com/v1"
}
- name API接口文档名称
- version API接口文档版本号
- description API接口文档简要描述
- title API接口文档生成的网页标题
- url API接口文档中请求的基本路径
上面是一个方法,其实还有一个方法
2.1 方式二
可以在package.json最后面加,这样相比上面的方式就不用再加一个文件了
"apidoc": {
"name": "用户管理",
"version": "0.1.0",
"description": "apiDoc 用户管理接口文档",
"title": "用户管理接口文档",
"url" : "https://api.github.com/v1"
}
3.编写Api
/**
* @api {post} http://localhost:3000/register 用户注册
* @apiDescription 用户注册
* @apiName submit-login
* @apiGroup User
* @apiParam (body) {String} email 用户邮箱
* @apiParam (body) {String} password 用户密码
*
* @apiSuccess {Number} code 错误状态码.
* @apiSuccess {String} msg 错误消息.
* @apiSuccessExample {json} Success-Response:
* {
* "code" : "0",
* "msg" : "注册成功"
*
* }
* @apiSampleRequest http://localhost:3000/register
* @apiVersion 1.0.0
*/
router.post("/register", userController.register);
在路由那块添加以上注释就可以让apidoc识别,生成文档,注解说明可见官网注解说明
4.运行命令,生成文档
命令:
$ apidoc -i ./ -o ./public/apidoc
在package.json中的scripts配置如下
"scripts": {
"docs": "apidoc -i ./routers -o ./public/docs",
}
-i 输入源目录名。项目文件的位置。
-o 输出目录名。放置生成的文档的位置。
通过本地域名去访问:http://localhost:3000/docs/index.html即可
以下是我通过docs生成的可以直接在线调试的api文档,功能简直不要太强大!