为了账号安全,请及时绑定邮箱和手机立即绑定

2.Nodejs + Express生成在线api接口文档

引言

为了更好的方便前后端联调,nodejs作为后台服务端代码,必须要能生成api接口文档,否则全部口头约定,非常不利于后期维护

这里就有了插件 apidoc

安装方法


npm install apidoc -g

全局安装即可,它是通过运行命令生成本地html文件的

配置文件

我们可以在根目录新建apidoc.json文件,配置如下


{

"name":  "test接口文档",

"title":  "test接口文档",

"description":"test接口文档说明",

"url"  :  "http://localhost:8111",

"version":  "1.0.0"

}

如果要生成文档,直接运行apidoc -i router/ -o apidoc/

(1).router/是要生成文档的目录

(2).apidoc/生成文档后存放的目录

为了方便,我们重启服务即生成文档,所以下面我们修改一下package.json,改一下运行脚本


apidoc -i router/ -o apidoc/ && cross-env NODE_ENV=development nodemon index.js --watch ./

有了这些配置后,我们对一下接口增加注释,即可生成文档

Express 接口

根目录下新建router目录,作为所有接口路由目录,目录下新建index.jsuser.js

router/index.js


var express =  require('express')

var router = express.Router()

  

var app =  express()

  

var user =  require('./user');

  

router.use('/user', user);

  

router.use('*', (req, res) => {

res.status(404).json({

code:  404,

message:  '404'

});

});

  

module.exports  = router

根目录index.js也得增加配置


const express =  require('express')

  

const app =  express()

  

const router =  require('./router')

  

var  api  =  function (req, res, next){

let ip = utils.getClientIP(req)

console.log(`====================${ip}, ${req.originalUrl}====================`)

console.log(`====================参数start====================`)

req.body =  Object.assign({}, req.body, req.query, req.params, {

ip: ip

})

console.log('body', JSON.stringify(req.body))

console.log(`====================参数end====================`)

next()

}

  

var user =  require('./user');

  

router.use('/user', api, user);

  

app.listen('8111', function () {

console.log("The server is running at *: 8111");

});

这样我们就直接在router/user.js编写我们的业务接口


var express =  require('express')

var router = express.Router();

var utils =  require('../utils')

  

const { Op } =  require("sequelize")

  

const userDB =  require('../db/model/user')

/**

*

* @api {get} /api/user/info 用户信息

* @apiName 用户信息

* @apiGroup 用户

* @apiDescription 返回用户详细信息

* @apiVersion 1.0.0

*

* @apiParam {String} id=''

*

* @apiParamExample {type} Request-Example:

* {

* id: 1

* }

*

* @apiSuccess {Number} code 200

* @apiSuccess {Object} data 用户信息

* @apiSuccessExample {type} Response-Example:

* {

* code: 200,

* data: {

* name: '',

* age: '',

* sex: '',

* ...

* }

* }

*

*/

router.get('/info', async (req, res) => {

const params = req.body;

if(!params.id){

utils.sendError(res, '用户ID不能为空')

return

}

let data =  await userDB.findOne({

raw:  true,

where: {

id: params.id

}

})

res.send({

code:  200,

data: data

})

})

  

module.exports  = router;

这里用的utils.js主要是对一些工具,公共的代码块做了一些封装,大家可以自行去看。

接口上方的注释部分就是apidoc的注解部分,信息解释:

(1)@api {post} /api/user/info 用户信息

{post/get}请求方式;/api/user/info接口地址;接口名字

(2)@apiName 接口名字

(3)@apiGroup 接口分组

(4)@apiDescription 描述

(5)@apiParam 请求参数

(6)@apiParamExample 请求参数示例

(7)@apiSuccess 响应数据

(8)@apiSuccessExample 响应数据示例

Ok,到这里我们重启服务,看看生成文档的样子有多可爱。

可以看到,项目更目录下已经生成了apidoc目录,我们浏览器访问试试。

发现不行,why?

Express访问静态资源

是因为我们没有apidoc目录开放出来,运行访问。所以,更目录index.js加入代码


app.use('/apidoc', express.static('apidoc'));

666,可以了!

接下来必须的试试咱们的接口,复制文档接口地址,访问试试:

到此,大功告成!Apidoc接口文档已生成,下次咱们处理处理日志。

点击查看更多内容
1人点赞

若觉得本文不错,就分享一下吧!

评论

作者其他优质文章

正在加载中
Web前端工程师
手记
粉丝
1.5万
获赞与收藏
5278

关注作者,订阅最新文章

阅读免费教程

感谢您的支持,我会继续努力的~
扫码打赏,你说多少就多少
赞赏金额会直接到老师账户
支付方式
打开微信扫一扫,即可进行扫码打赏哦
今天注册有机会得

100积分直接送

付费专栏免费学

大额优惠券免费领

立即参与 放弃机会
意见反馈 帮助中心 APP下载
官方微信

举报

0/150
提交
取消