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，即可看见接口文档。