跳转至

对比与动机

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)。
  • FlaskBlueprint 类添加路由快捷方式(在 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 响应。
  • 支持类视图。
  • ……