Vue + Flask 实战开发系列（五）

TalkPython

接口开发完成以后，并不代表编程就结束了。因为接口会被很多个客户端所使用，例如：Web端，Android端，iOS端，小程序端等。因此这也就表示接口会被其他开发人员所使用，集成API文档是非常的必要。API文档是一个REST的应用程序的重要组成部分。

环境准备与集成

在这一部分，我们主要来完成为集成API文档工作。用的Flask扩展包是下面这两个，你可以提前安装。

$(venv) pip install flask_swagger$(venv) pip install flask_swagger_ui

安装完成之后，让我们把它集成到应用程序中。首先，打开main.py文件，编写一个接口文档的路由，增加如下程序。


from flask_swagger import swagger
from flask import jsonify

@app.route("/api/spec")
def spec():
    swag = swagger(app,prefix='/api')
    swag['info']['base'] = "http://locahost:5000"
    swag['info']['version'] = "1.0"
    swag['info']['title'] = 'Flask API Docs'
    return jsonify(swag)

程序编写完成后，继续打开app/init.py文件，添加如下代码程序。


from flask_swagger_ui import get_swaggerui_blueprint

# 下面两行程序,添加到register_blueprints函数中
swaggerui_blueprint = get_swaggerui_blueprint('/api/docs','/api/spec',config={'app_name':'Flask API Docs'})
app.register_blueprint(swaggerui_blueprint,url_prefix='/api/docs')

以上程序都编写完成后，运行我们的Flask应用。

$(venv）flask run

应用运行程序成功后，在浏览器访问地址http://localhost:5000/api/docs/，一切正常的话，就会看到下面这样的内容。

编写API文档

接口文档信息，我们这里使用yaml格式来写。采用注释的方法，写在每一个接口函数里面。具体来看一个实例。下面这个实例是注册用户接口的接口文档。打开app/users/routes.py文件，编写程序。最终编写完成的程序，见下面：


@users_bp.route('/register', methods=['POST'])
def create_user():
    """
    用户注册接口
    ---
    parameters:
        - in: body
          name: body
          schema:
            required:
                - username
                - password
            properties:
                username:
                    type: string
                    description: 用户名
                    default: ""
                password:
                    type: string
                    description: 用户密码
                    default: ""
    responses:
        201:
            description: 注册成功
            schema:
                properties:
                    code:
                        type: string
        422:
            description: 注册失败
            schema:
                properties:
                    code:
                        type: string
                    message:
                        type: string
    """
    try:
        data = request.get_json()
        data['password'] = User.generate_hash(data['password'])
        user_schema = UserSchema()
        users = user_schema.load(data)
        result = user_schema.dump(users.create())
        return response_with(resp.SUCCESS_201)
    except Exception as e:
        print(e)
        return response_with(resp.INVALID_INPUT_422)

上面程序中注释部分，就是我们写的接口文档。这时你运行程序，就可以看到我们的编写的接口文档相信。

$(venv) flask run

Flask应用运行成功后，访问接口文档地址：http://127.0.0.1:5000/api/docs/。最终看到下面的结果，就说明成功了。

在这里我们可以到接口的注册用户接口的请求地址、请求参数、响应结果等信息。其他的接口也是这样的方法进行增加，在此不再赘述。本次分享的全部内容，全文至此完。