APIFlask

APIFlask 是一个基于 Flask 和 marshmallow-code 项目构建的轻量级 Python 网络API框架。它易于使用，高度可定制，与 ORM/ODM 无关，并且 100% 兼容 Flask 生态系统。

使用 APIFlask，您将获得：

• 更多视图函数糖（如 @app.input()、@app.output()、@app.get()、@app.post() 等）
• 自动请求验证和反序列化
• 自动响应格式化和序列化
• 自动生成 OpenAPI 规范 (OAS，以前称为 Swagger 规范) 文档
• 自动交互式 API 文档
• API 认证支持（通过 Flask-HTTPAuth）
• 自动 JSON 响应 HTTP 错误

需求

• Python 3.8+
• Flask 2.0+

安装

对于 Linux 和 macOS

$ pip3 install apiflask

对于 Windows

> pip install apiflask

链接

• 网站： https://apiflask.com
• 文档： https://apiflask.com/docs
• PyPI 发布： https://pypi.python.org/pypi/APIFlask
• 变更日志： https://apiflask.com/changelog
• 源代码： https://github.com/apiflask/apiflask
• 问题跟踪器： https://github.com/apiflask/apiflask/issues
• 讨论： https://github.com/apiflask/apiflask/discussions
• 推特： https://twitter.com/apiflask
• Open Collective： https://opencollective.com/apiflask

捐赠

如果您认为 APIFlask 有用，请考虑今天 捐赠。您的捐赠使 APIFlask 保持维护和不断发展。

感谢所有支持者和赞助商！

支持者

赞助商

示例

from apiflask import APIFlask, Schema, abort
from apiflask.fields import Integer, String
from apiflask.validators import Length, OneOf

app = APIFlask(__name__)

pets = [
    {'id': 0, 'name': 'Kitty', 'category': 'cat'},
    {'id': 1, 'name': 'Coco', 'category': 'dog'}
]


class PetIn(Schema):
    name = String(required=True, validate=Length(0, 10))
    category = String(required=True, validate=OneOf(['dog', 'cat']))


class PetOut(Schema):
    id = Integer()
    name = String()
    category = String()


@app.get('/')
def say_hello():
    # returning a dict or list equals to use jsonify()
    return {'message': 'Hello!'}


@app.get('/pets/<int:pet_id>')
@app.output(PetOut)
def get_pet(pet_id):
    if pet_id > len(pets) - 1:
        abort(404)
    # you can also return an ORM/ODM model class instance directly
    # APIFlask will serialize the object into JSON format
    return pets[pet_id]


@app.patch('/pets/<int:pet_id>')
@app.input(PetIn(partial=True))  # -> json_data
@app.output(PetOut)
def update_pet(pet_id, json_data):
    # the validated and parsed input data will
    # be injected into the view function as a dict
    if pet_id > len(pets) - 1:
        abort(404)
    for attr, value in json_data.items():
        pets[pet_id][attr] = value
    return pets[pet_id]

from apiflask import APIFlask, Schema, abort
from apiflask.fields import Integer, String
from apiflask.validators import Length, OneOf
from flask.views import MethodView

app = APIFlask(__name__)

pets = [
    {'id': 0, 'name': 'Kitty', 'category': 'cat'},
    {'id': 1, 'name': 'Coco', 'category': 'dog'}
]


class PetIn(Schema):
    name = String(required=True, validate=Length(0, 10))
    category = String(required=True, validate=OneOf(['dog', 'cat']))


class PetOut(Schema):
    id = Integer()
    name = String()
    category = String()


class Hello(MethodView):

    # use HTTP method name as class method name
    def get(self):
        return {'message': 'Hello!'}


class Pet(MethodView):

    @app.output(PetOut)
    def get(self, pet_id):
        """Get a pet"""
        if pet_id > len(pets) - 1:
            abort(404)
        return pets[pet_id]

    @app.input(PetIn(partial=True))
    @app.output(PetOut)
    def patch(self, pet_id, json_data):
        """Update a pet"""
        if pet_id > len(pets) - 1:
            abort(404)
        for attr, value in json_data.items():
            pets[pet_id][attr] = value
        return pets[pet_id]


app.add_url_rule('/', view_func=Hello.as_view('hello'))
app.add_url_rule('/pets/<int:pet_id>', view_func=Pet.as_view('pet'))

$ pip install -U "apiflask[async]"

import asyncio

from apiflask import APIFlask

app = APIFlask(__name__)


@app.get('/')
async def say_hello():
    await asyncio.sleep(1)
    return {'message': 'Hello!'}

将其保存为 app.py，然后运行它

$ flask run --reload

或在调试模式下运行

$ flask run --debug

现在访问交互式 API 文档（Swagger UI）http://localhost:5000/docs

您还可以通过在创建 APIFlask 实例时使用 docs_ui 参数来更改 API 文档 UI

app = APIFlask(__name__, docs_ui='redoc')

现在 http://localhost:5000/docs 将使用 Redoc 渲染 API 文档

支持的 docs_ui 值（UI 库）包括

• swagger-ui（默认值）：Swagger UI
• redoc：Redoc
• elements：Elements
• rapidoc：RapiDoc
• rapipdf：RapiPDF

自动生成的 OpenAPI 规范文件可在 http://localhost:5000/openapi.json 获取。您也可以使用 “flask spec”命令 获取规范

$ flask spec

有关一些完整示例，请参阅 /examples。

与 Flask 的关系

APIFlask 是 Flask 之上的一个薄层封装。您只需要记住以下区别（有关更多详细信息，请参阅 从 Flask 迁移）

• 在创建应用程序实例时，请使用 APIFlask 而不是 Flask。
• 在创建蓝图实例时，请使用 APIBlueprint 而不是 Blueprint。
• APIFlask（《apiflask.abort》）中的abort()函数返回JSON错误响应。

对于一个最小的Flask应用

from flask import Flask, request
from markupsafe import escape

app = Flask(__name__)

@app.route('/')
def hello():
    name = request.args.get('name', 'Human')
    return f'Hello, {escape(name)}'

现在改为APIFlask

from apiflask import APIFlask  # step one
from flask import request
from markupsafe import escape

app = APIFlask(__name__)  # step two

@app.route('/')
def hello():
    name = request.args.get('name', 'Human')
    return f'Hello, {escape(name)}'

总的来说，为了使Flask中的Web API开发更加容易，APIFlask提供了APIFlask和APIBlueprint来扩展Flask的Flask和Blueprint对象，并且还附带了一些有用的工具。除此之外，你实际上仍在使用Flask。

与marshmallow的关系

APIFlask接受marshmallow模式作为数据模式，使用webargs来验证请求数据与模式，并使用apispec从模式生成OpenAPI表示。

你可以像以前一样构建marshmallow模式，但APIFlask还公开了一些 marshmallow API 以方便使用

• apiflask.Schema：基 marshmallow 模式类。
• apiflask.fields：marshmallow 字段，包含来自 marshmallow 和 Flask-Marshmallow 的字段。请注意，别名（Url、Str、Int、Bool等）已被删除。
• apiflask.validators：marshmallow 验证器。

from apiflask import Schema
from apiflask.fields import Integer, String
from apiflask.validators import Length, OneOf
from marshmallow import pre_load, post_dump, ValidationError

致谢

APIFlask最初是APIFairy的分支，并受到flask-smorest和FastAPI的启发（有关这些项目之间的比较，请参阅比较和动机）。