对比与动机¶
APIFlask 基于 APIFairy(它和 flask-smorest 提供类似的 API)的一个 fork 实现,并受到 flask-smorest 和 FastAPI 的启发。那么,APIFlask 与 APIFairy/flask-smorest/FastAPI 之间有什么区别呢?
简而言之,对于使用 Flask 开发 Web API,我试图提供一个优雅(作为框架,不需要实例化额外的扩展对象)和简单的(对 OpenAPI/API 提供更多自动化支持)解决方案。以下是 APIFlask 和相似项目差异的总结。
APIFlask vs FastAPI¶
- 对于 Web 部分,FastAPI 基于 Starlette 构建,而 APIFlask 基于 Flask 构建。
- 对于数据处理部分(序列化/反序列化,OpenAPI 支持),FastAPI 依赖于 Pydantic,而 APIFlask 使用 marshmallow-code 项目(marshmallow、webargs、apispec)。
- APIFlask 基于 Flask 开发,因此它与 Flask 扩展相兼容。
- FastAPI 支持异步。APIFlask 基于 Flask 2.0+ 可以实现基本的异步支持。
- APIFlask 提供了更多的装饰器来帮助更好地组织代码。
- FastAPI 将输入数据作为对象注入,而 APIFlask 则使用字典传递。
- APIFlask 基于 Flask 的
MethodView
实现了内置的类视图支持。 - 除了 Swagger UI 和 Redoc,APIFlask 还支持更多的 API 文档工具:Elements、RapiDoc 和 RapiPDF。
APIFlask vs APIFairy/flask-smorest¶
APIFlask 是一个框架¶
虽然 APIFlask 是 Flask 之上的一层薄薄的包装,但它实际上是一个框架。因此,无需实例化其他扩展对象:
from flask import Flask
from flask_api_extension import APIExtension
app = Flask(__name__)
api = APIExtension(app)
只需使用 APIFlask
类来替换 Flask
类:
from apiflask import APIFlask
app = APIFlask(__name__)
将 APIFlask 设计为框架而不是 Flask 扩展的关键原因在于,这使得覆盖和更改 Flask 的内部行为成为可能。例如:
- 重写
Flask.dispatch_request
以确保注入到视图函数中的参数的自然顺序(APIFlask 1.x)。 - 为
Flask
和Blueprint
类添加路由快捷方式(在 Flask 2.0 中添加)。 - 重写
Flask.make_response
以支持将列表作为 JSON 响应返回(在 Flask 2.2 中添加)。 - 重写
Flask.add_url_rule
以支持为基于类的视图生成 OpenAPI 规范。
OpenAPI 生成更加自动化¶
- 根据视图函数的名称为视图函数添加自动摘要(summary)。
- 为仅使用路由修饰符的裸视图函数添加成功响应(200)。
- 为使用
input
装饰器的视图函数添加验证错误响应(422)。 - 为使用
auth_required
装饰器的视图函数添加认证错误响应(401)。 - 为包含 URL 变量的视图函数添加 404 响应。
- 为使用
doc
装饰器的视图函数的潜在错误响应添加响应 schema,例如doc(responses=[404, 405])
。 - ……
Tip
你可以使用相关的配置变量更改这些自动化行为。
功能更丰富和完善¶
- 添加
doc
装饰器来允许以显式方式为视图函数设置 OpenAPI spec。 - 支持设置更多 OpenAPI 字段(
info
的所有子字段、servers
、响应/请求体/参数的example
、路径deprecated
等)。 - 支持自定义 API 文档的配置和 CDN 网址。
- 默认为所有 HTTP 错误和认证错误返回 JSON 响应。
- 支持类视图。
- ……