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

版权声明：找不到大腿的时候,让自己变成大腿. https://blog.csdn.net/Xin_101/article/details/88121486

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

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

---