Flaskerk

为Flask服务提供OpenAPI文档和验证。

主要用于机器学习模型服务。

如果你使用Falcon，请查看我的另一个库Falibrary。

功能

• 使用Redoc UI或Swagger UI生成API文档：yum
• 更少的模板代码，注释非常易于使用：sparkles
• 使用pydantic验证查询、JSON数据和响应数据：wink
• 更好的API服务的HTTP异常（默认和自定义）（JSON而不是HTML）：grimacing

快速开始

使用pip install flaskerk安装（Python 3.6+）

简单示例

from flask import Flask, request, jsonify
from flaskerk import Flaskerk
from pydantic import BaseModel

class Query(BaseModel):
    text: str

app = Flask(__name__)
api = Flaskerk()

@app.route('/api/classify')
@api.validate(query=Query)
def classify():
    print(request.query)
    return jsonify(label=0)

if __name__ == "__main__":
    api.register(app)
    app.run()

需要更改的内容

• 使用pydantic创建模型
• 使用Flaskerk.validate()装饰路由函数
• 在validate中指定需要哪些部分
  • query（URL中的参数）
    • 内置转换器（字符串、路径、任何、整数、浮点数、uuid）
  • data（请求的JSON数据）
  • resp（响应）这将验证后转换为JSON数据
  • x（HTTP异常列表）
  • tags（此API路由的标签）
• 注册到Flask应用

之后，这个库将帮助您验证传入的请求，并在/docs中提供API文档。

有关更多详细信息，请参阅文档。

更多功能

from flask import Flask, request
from pydantic import BaseModel, Schema
from random import random
from flaskerk import Flaskerk, HTTPException

app = Flask(__name__)
api = Flaskerk(
    title='Demo Service',
    version='1.0',
    ui='swagger',
)

class Query(BaseModel):
    text: str

class Response(BaseModel):
    label: int
    score: float = Schema(
        ...,
        gt=0,
        lt=1,
    )

class Data(BaseModel):
    uid: str
    limit: int
    vip: bool

e233 = HTTPException(code=233, msg='lucky for you')

@app.route('/api/predict/<string(length=2):source>/<string(length=2):target>', methods=['POST'])
@api.validate(query=Query, data=Data, resp=Response, x=[e233], tags=['model'])
def predict(source, target):
    """
    predict demo

    demo for `query`, `data`, `resp`, `x`
    """
    print(f'=> from {source} to {target}')  # path
    print(f'Data: {request.json_data}')  # Data
    print(f'Query: {request.query}')  # Query
    if random() < 0.5:
        e233.abort('bad luck')
    return Response(label=int(10 * random()), score=random())

if __name__ == '__main__':
    api.register(app)
    app.run()

尝试使用以下命令：http POST ':5000/api/predict/zh/en?text=hello' uid=0b01001001 limit=5 vip=true

在http://127.0.0.1:5000/docs 中打开文档。

更多示例，请查看示例。

常见问题解答

我可以在不生成API文档的情况下进行验证吗？

当然可以。如果你没有将其注册到Flask应用中，将不会有文档路由。