node + express + sequelize + apidoc 后台初始化

技术栈：express-generator + sequelize + apidoc

一、创建应用骨架：

express官网

1. 创建文件夹，名称为：express
2. cd到express文件夹，运行Express应用程序生成器

npx express-generator

3. 安装依赖包

npm install

4. 启动应用

set DEBUG=express:* & npm start

或者

npm start

5. 查看应用

浏览器打开：localhost:3000

二、安装常用插件

1. nodemon，热更新
修改package.json启动命令，采用nodemon启动项目

"scripts": {
    "start": "nodemon ./bin/www"
},

2. 数据库

• 电脑安装mysql
  运行mysql，并使用navicat连接

参考地址

• 数据库依赖
  sequelize：一个基于 promise 的 Node.js ORM, 目前支持 Postgres, MySQL, MariaDB, SQLite 以及 Microsoft SQL Server. 它具有强大的事务支持, 关联关系, 预读和延迟加载,读取复制等功能。
  sequelize官网
  mysql2
• 连接数据库
  根目录下新建db.js

const Sequelize = require('sequelize')

const sequelize = new Sequelize(数据库名称, 数据库账户, 数据库密码, {
    host: 'localhost',
    port: '3306',
    dialect: 'mysql',
    define: {
        // 全局禁用时间戳，不然数据表里需要创建时间戳列；或者每次创建表时单独禁用或创建时间戳列。否则会报错。
        timestamps: false
    }
})

sequelize.authenticate().then(() => {
    console.log('database connection has been established successfully.')
}).catch(err => {
    console.log('unable to connect to the database', err)
})

module.exports = sequelize

根目录下新建models文件夹，然后在models文件夹下新建user.js文件

const Sequelize = require('sequelize')
const sequelize = require('../db')
const db = require('../db')

// 模型定义
const User = db.define('User', {
    id: {
        type: Sequelize.INTEGER(11),
        primaryKey: true
    },
    username: {
        type: Sequelize.STRING(0)
    },
    password: {
        type: Sequelize.STRING(12)
    }
})

// 模型同步
// 立即执行函数如果报错，加上分号再试
; (async () => {
    // User.sync() - 如果表不存在,则创建该表(如果已经存在,则不执行任何操作)
    await User.sync()
})();


module.exports = User

修改routes文件夹下的user.js文件

var express = require('express');
var router = express.Router();

const User = require('../models/user')

/**
@api {get} /user/:id Request User information
 * 
@apiName GetUser
 * 
@apiGroup User
 *
 * @apiParam {Number} id Users unique ID.
 *
 * @apiSuccess {String} firstname Firstname of the User.
 * @apiSuccess {String} lastname  Lastname of the User.
 *
 * @apiSuccessExample Success-Response:
 *     HTTP/1.1 200 OK
 *     {
 *       "firstname": "John",
 *       "lastname": "Doe"
 *     }
 *
 * @apiError UserNotFound The 
id of the User was not found.
 *
 * @apiErrorExample Error-Response:
 *     HTTP/1.1 404 Not Found
 *     {
 *       "error": "UserNotFound"
 *     }
 */

/* GET users listing. */
router.get('/', async function(req, res, next) {
  const data = await User.findAll()
  res.send({
    data
  });
});

router.get('/add', async function(req, res, next) {
  const oldData = await User.findAll()
  const len = oldData.length
  const user = await User.create({
    id: len,
    username: `user_${len}`,
    password: `password_${len}`
  })
  const data = await User.findAll()
  res.send({
    data
  });
});

module.exports = router;

3. 接口文档
apidoc
apidoc官网
项目根目录下添加apidoc.json文件，这个文件主要包含一些项目的描述信息，例如标题、介绍、版本等。

{
    "name": "example",
    "version": "0.1.0",
    "description": "apiDoc basic example",
    "title": "Custom apiDoc browser title",
    "url": "https://api.github.com/v1"
}

在代码注释里加入apidoc的注解。apidoc不在乎把注释写在哪里，不过还是推荐写在接口所在位置。
上一步：修改routes文件夹下的user.js文件，已加入注释代码。

/**
@api {get} /user/:id Request User information
 * 
@apiName GetUser
 * 
@apiGroup User
 *
 * @apiParam {Number} id Users unique ID.
 *
 * @apiSuccess {String} firstname Firstname of the User.
 * @apiSuccess {String} lastname  Lastname of the User.
 *
 * @apiSuccessExample Success-Response:
 *     HTTP/1.1 200 OK
 *     {
 *       "firstname": "John",
 *       "lastname": "Doe"
 *     }
 *
 * @apiError UserNotFound The 
id of the User was not found.
 *
 * @apiErrorExample Error-Response:
 *     HTTP/1.1 404 Not Found
 *     {
 *       "error": "UserNotFound"
 *     }
 */

常用的一些注解如下：
apidoc仅解析含有@api或者@apiDefine的注释块。
@apiDefine一个注释块中仅能有一个，@apiDefine可以定义一些通用的内容，比如通用的请求参数，返回值，错误列表等 。
@api 用来定义一个api，需要注意的是，@apiGroup和@apiName是必须的，@apiGroup定义的是左侧导航，@apiName 会拼接到访问路径中。@apiGroup不支持中文，需要和@apiDefine配合使用。

@api 定义API的请求方法、路径和名字
@apiDescription 定义API的描述
@apiGroup 定义API的分组
@apiParam 定义API的参数
@apiParamExample 参数请求的事例
@apiVersion 版本
@apiErrorExample API错误示例
@apiSuccessExample API正常示例

项目根目录下执行：

apidoc -i ./ -o apidoc

• i 是输入源, -i ./ 表示 要生成apidoc接口文档的项目目录就是当前目录
• o 是输出 ，-o apidoc 表示当前目录下apidoc 是接口文档的输出目录
  输入输出目录 根据自己需求更改。
  生成的apidoc目录下，包含了所有接口注释信息，浏览器打开文件夹下index.html，即可看见接口文档。