apiDoc的使用

apiDoc的使用

安装

• 安装node环境
• 全局安装apiDoc

npm install apidoc -g

• 安装flask-apidoc扩展包

pip install flask-apidoc
pip install flask-script

配置文件

• 项目启动脚本文件配置

manage.py

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()

• apiDoc配置文件

apidoc.json

{
 "name": "MyProject REST API",
 "version": "1.0.0",
 "description": "A Flask REST API DOC",
 "title": "MyProjectAPI",
 "url" : "http://localhost:5000"
}

该配置文件要放入到项目根目录。

参数	含义
name	项目名称（自命名）
version	项目接口版本号
description	项目描述
title	项目标题
url	接口访问地址

文档注释说明

注释	说明
@api {post} url	中括号为请求方式；url为请求地址
@apiVersion 1.0.0	接口版本号
@apiName name	接口名称
@apiGroup users	接口组名
@apiParam {String} name	传入参数类型和名称
@apiParamExample {json} Request-Example: { mobile: “13970512239”, password: “123456”, }	传入参数示例
@apiSuccess (回参) {String} name 用户昵称	返回参数

注释示例

class UserController(Resource,BaseController):

    """
    @api {get} /api/v1/user 微信登录
    @apiVersion 1.0
    @apiName 微信登录
    @apiGroup 微信小程序
    @apiParam {String}  code      (必须)    微信小程序登录提供的code
    @apiParamExample {json} Request-Example:
        {
            code: "512239",
        }

    @apiSuccess (回参) {json} data  返回json数据
    @apiSuccess (回参) {int} error_code  错误代码
    @apiSuccess (回参) {String} msg  错误信息
    @apiSuccessExample {json} Success-Response:
        {
            "data": "", 
            "error_code": 200, 
            "msg": ""
        }

    @apiErrorExample {json} Error-Response:
        {
            "error": true, 
            "error_code": 400, 
            "msg": "Get Openid Failed"
        }
    """

    def get(self):
        code = self.request_dic_data(['code'])['code']
        if not code :
            return self.error('No Code Information')
        try:
            url = "https://api.weixin.qq.com/sns/jscode2session?appid=%s&secret=%s&js_code=%s&grant_type=authorization_code"
            response = req.get(url%(APP_ID,SECRET_KEY,code))
            res_json = json.loads(response.text)
            open_id = res_json.get("openid")
            # sesssion_key = res_json.get("session_key")
            if not open_id:
                return self.error("Get Openid Failed")
            session['open_id'] = open_id
            return self.success_data()
        except:
            traceback.print_exc()
            return self.error()

运行apiDoc

执行命令运行生成接口文档：

python manage.py apidoc

• 通过命令生成接口文档

apidoc -i src -o output_file_name

其中src是源文件目录，output_file_name是输出文件目录。

运行截图

用户密码加密

​ 对于用户提交的密码不能以明文的方式保存到数据需要对明文密码提取摘要保存。由于MD5现在已经被破解所以这里不再使用MD5对文件提取摘要这里使用python的werkzeug.security库。示例代码如下：

#!/usr/bin/env python
# -*- coding: utf-8 -*-
'''
@File    :   Password.py
@Time    :   2022/11/18 17:56:27
@Author  :   yiyizhang 
@Version :   1.0
'''

from werkzeug.security import check_password_hash, generate_password_hash

class Password():
    
    """
    @param pwd 明文密码
    @return hash密码
    @example pbkdf2:sha256:260000$JGYS4GnDa6BLFRkp$2e0027b721cff3675bc9501df6f4aec1617f4c7dca5b2cb5ff433eb4da553cd7
    @other hash密码为102位
    """
    @staticmethod
    def generate_pwd_hash(pwd=""):
        return generate_password_hash(pwd)

    """
    @param _hash 加密hash值
    @pwd 明文密码
    @return True or False
    """
    @staticmethod
    def check_pwd_hash(_hash="",pwd=""):
        return check_password_hash(_hash,pwd)

​ 这里使用的是sha256对明文提取摘要同时在操作的同时引入salt，这样加强对弱密码的保护。