一个学习编程技术的公众号。每天推送高质量的优秀博文、开源项目、实用工具、面试技巧、编程学习资源等等。目标是做到个人技术与公众号一起成长。欢迎大家关注,一起进步,走向全栈大佬的修炼之路
效果
背景
之前做前端的时候,后端同学仗着自己是老同志,不给我接口文档
苦逼如我,需要拿着笔坐在他的旁边,听他口述
写下需要的api接口url和参数等等
现在自己做后端了,那不能这样子胡作非为了
自己吃的苦,怎能给其他同学吃呢?
这时候,apiDoc你值得拥有,稳稳的输出一篇优质的接口文档
安装apidoc
官网上是全局安装,我是喜欢安装到项目中,这样可以在另一个环境下,npm install
就可以下载有所有依赖包
npm install apidoc --save-dev/-D
写注释
注册接口的注释
/**
* @api {post} /v1/auth/register User Register
* @apiName UserRegister
* @apiGroup userAuthentication
*
* @apiParam {String} username New user's username.
* @apiParam {String} password New user's password.
*
* @apiSuccess {String} username The username of the register user.
* @apiSuccess {string} message The registering success info.
*
* @apiSuccessExample Success-Response:
* HTTP/1.1 200 OK
* {
* "username": "username",
* "message": "User registered successful"
* }
*
* @apiError REGISTER_FAILURE The register failure.
*
* @apiErrorExample Error-Response:
* HTTP/1.1 500 Internal Server Error
* {
* "err": "REGISTER_FAILURE",
* "message": "User register failure!"
* }
*/
删除接口的注释
/**
* @api {delete} /v1/auth/user/ User delete
* @apiName UserDelete
* @apiGroup userAuthentication
*
* @apiParam {String} username User's username.
* @apiParam {String} executor Executor of this operation.
*
* @apiSuccess {String} username The username of the deleted user.
* @apiSuccess {string} message The message if deleting successful.
*
* @apiSuccessExample Success-Response:
* HTTP/1.1 200 OK
* {
* "username": "username",
* "message": "Delete User Successful"
* }
*
* @apiError NOT_LOGIN The register failure.
*
* @apiErrorExample Error-Response:
* HTTP/1.1 401 Unauthorized
* {
* "err": "NOT_LOGIN",
* "message": "User has not logon in!"
* }
*/
写入命令
将apidoc -i routers/
写入package.json的命令中
routers文件夹下都是路由文件
"scripts": {
"test"