Flask+Nodejs开发Restful风格接口文档

1 环境及部署

1.0 基础环境

• Ubuntu18.04
• Flask
• flask-apidoc
• flask-script
• flask-cors
• nodejs
• npm(nodejs包管理)

1.2 运行环境

• body-parser1.18.2
• cookie-parser1.4.3
• debug2.6.9
• ejs2.5.7
• express4.15.5
• morgan1.9.0
• serve-favicon2.4.5
• pm2

1.3 环境部署

• nodejs环境

sudo apt-get install nodejs
sudo apt install npm
sudo npm install apidoc -g
sudo cpm pm2
sudo cnpm i

• flask环境

pip3 install flask
pip3 install flask-script
pip3 install flask-apidoc
pip3 install flask-cors

2 生成API接口文档

2.1 flask文件结构

|-- api_doc_flask
|   |-- __pycache__
|   |   `-- views.cpython-36.pyc
|   |-- apidoc.json
|   |-- run.py
|   `-- views.py

2.2 文件内容

2.2.1 apidoc.json

API文档说明.

{
 "name": "REST API",
 "version": "1.0.0",
 "description": "REST API show",
 "title": "REST API",
 // URI前缀,若使用多个port可忽略url
 // 直接在{get}或{post}添加URI即可
 "url" : "http://localhost:8090"
}

2.2.2 views.py

API接口结构内容,写在route中,每个route代表一个接口,和flask接口模式相同.

from flask import Flask, render_template 
from flask_apidoc import ApiDoc 

app = Flask(__name__)

doc = ApiDoc(app=app)

@app.route('/post', methods=['POST', 'GET'])
def register():
	"""
	@api {post} http://localhost:8090/api/v1.0/register 注册 
	@apiVersion 1.0.0
	@apiName register_user
	@apiGroup Users 
	@apiParam {String} mobile (必须)用户手机号
	@apiParam {String} password (必须)用户密码
	@apiParam {String}sms_code (必须)用户短信验证码
	@apiParamExample {json} 请求样例json:
	{
		"mobile": "123456",
		"password": "123456",
		"sms_code": "123456"
	}
	@apiSuccess (回参) {int} user_id 用户注册id
	@apiSuccess (回参) {String} name 用户昵称
	@apiSuccess (回参) {String} mobile 用户注册手机号
	@apiSuccess (回参) {String} avatar 用户头像地址
	@apiSuccess (回参) {String} create_time 用户创建时间
	@apiSuccessExample {json} 请求成功:
	{
		"errno":0,
		"errmsg":"注册成功",
		"data":{
			"user_id":250,
			"name":"tianlanlan",
			"mobile":"123456",
			"avatar":"http://www.test.com",
			"create_time":"2019"
		}
	}
	@apiErrorExample {json} 请求异常:
	{
		"errno":250,
		"errmsg":"数据库查询错误"
	}
	"""
	pass

@app.route('/get', methods=['POST'])
def get_test():
	"""
	@api {get} http://localhost:8091/api/v1.0/connect 连接测试
	@apiVersion 1.0.0
	@apiGroup Connect
	@apiParam {String} id (必须)用户ID
	@apiParamExample {form-data} 请求样例form-data:
	id = 250
	@apiSuccess (返回参数) {String} info 连接状态
	@apiSuccessExample {json} 请求成功:
	{
		"errno":200,
		"errmsg":"请求成功",
		"data":{
			"info":"Successfully connection!"
		}
	}
	@apiErrorExample {json} 请求异常:
	{
		"errno":250,
		"errmsg":"连接异常"
	}
	"""
	pass

2.2.3 run.py

运行服务生成API接口文档文件.

from views import app
from flask_apidoc.commands import GenerateApiDoc
from flask_script import Manager

manager = Manager(app)
manager.add_command('apidoc', GenerateApiDoc())

if __name__ == "__main__":
	manager.run()

• 运行命令

python run.py apidoc

2.2.4 static接口文件

生成接口文档,目录如下:

|-- static
|   |   `-- docs
|   |       |-- api_data.js
|   |       |-- api_data.json
|   |       |-- api_project.js
|   |       |-- api_project.json
|   |       |-- css
|   |       |-- fonts
|   |       |-- img
|   |       |-- index.html
|   |       |-- locales
|   |       |-- main.js
|   |       |-- utils
|   |       `-- vendor

其中index.html为API接口界面,直接可浏览器打开,其他文件为js和css等辅助文件.

3 Nodejs部署服务

3.1 批量安装依赖

node文件结构:

|-- nodeServer
|   |-- app.js
|   |-- bin
|   |   `-- www
|   |-- node_modules [error opening dir]
|   |-- nodeserver.sh
|   |-- package.json
|   |-- public
|   |   |-- api_data.js
|   |   |-- api_data.json
|   |   |-- api_project.js
|   |   |-- api_project.json
|   |   |-- css
|   |   |-- fonts
|   |   |-- img
|   |   |-- index.html
|   |   |-- locales
|   |   |-- main.js
|   |   |-- utils
|   |   `-- vendor
|   |-- routes
|   |   |-- index.js
|   |   `-- users.js
|   `-- views
|       |-- error.ejs
|       `-- index.ejs

批量安装package.json的依赖.

{
  "dependencies": {
    "body-parser": "~1.18.2",
    "cookie-parser": "~1.4.3",
    "debug": "~2.6.9",
    "ejs": "~2.5.7",
    "express": "^4.15.5",
    "morgan": "~1.9.0",
    "serve-favicon": "~2.4.5"
  }
}

sudo cnpm i

3.2 运行服务

• 文件处理
  将生成的static/docs的文件复制到public文件夹下.
• 运行服务

node bin/www

pm2 start nodeserver.sh

【pm2指令】

序号	指令	描述
1	pm2 start script.sh	启动 bash 脚本
2	pm2 list	列表 PM2 启动的所有的应用程序
3 pm2 monit	显示每个应用程序的CPU和内存占用情况
4	pm2 show [app-name]	显示应用程序的所有信息
5	pm2 logs	显示所有应用程序的日志
6	pm2 logs [app-name]	显示指定应用程序的日志
7	pm2 flush	清洗所有的数据
8	pm2 stop all	停止所有的应用程序
9	pm2 stop 0	停止 id为 0的指定应用程序
10	pm2 restart all	重启所有应用
11	pm2 reload all	重启 cluster mode下的所有应用
12	pm2 gracefulReload all	Graceful reload all apps in cluster mode
13	pm2 delete all	关闭并删除所有应用
14	pm2 delete 0	删除指定应用 id 0
15	pm2 scale api 10	把名字叫api的应用扩展到10个实例
16	pm2 reset [app-name]	重置重启数量
17	pm2 startup	创建开机自启动命令
18	pm2 save	保存当前应用列表
19	pm2 resurrect	重新加载保存的应用列表

3.3 访问接口

localhost:8090/index.html

图3.1 API接口文档

4 总结

(1) API接口文档生成步骤:构建flask运行框架,生成API接口文档,搭建Nodejs服务,运行接口服务;
(2) 由于flask的前端使用jinja2,与生成的html结构有冲突,所以使用nodejs服务运行前端,可将接口文档完成线上部署.

---

[参考文献]
[1]https://blog.csdn.net/lynnyq/article/details/79254290
[2]https://www.jb51.net/article/134589.htm

---