Comparison and Motivations¶
APIFlask starts as a fork of APIFairy (which share similar APIs with flask-smorest) and is inspired by flask-smorest and FastAPI. So, what are the differences between APIFlask and APIFairy/flask-smorest/FastAPI?
In a word, I try to provide an elegant (act as a framework, no need to instantiate additional extension object) and simple (more automation support for OpenAPI/API documentation) solution for creating web APIs with Flask. Here is a summary of the differences between APIFlask and similar projects.
APIFlask vs FastAPI¶
- For the web part, FastAPI builds on top of Starlette, while APIFlask builts on top of Flask.
- For the data part (serialization/deserialization, OpenAPI support), FastAPI relies on Pydantic, while APIFlask uses marshmallow-code projects (marshmallow, webargs, apispec).
- APIFlask builds on top of Flask, so it's compatible with Flask extensions.
- FastAPI supports async. APIFlask has the basic async support with Flask 2.0.
- APIFlask provides more decorators to help organize things better.
- FastAPI injects the input data as an object, while APIFlask passes it as a dict.
- APIFlask has built-in class-based views support based on Flask's
- On top of Swagger UI and Redoc, APIFlask supports more API documentation tools: Elements, RapiDoc, and RapiPDF.
APIFlask vs APIFairy/flask-smorest¶
APIFlask is a framework¶
Although APIFlask is a thin wrapper on top of Flask, it's actually a framework. Thus, there is no need to instantiate additional extension object:
from flask import Flask from flask_api_extension import APIExtension app = Flask(__name__) api = APIExtension(app)
You only need to use the
APIFlask class to replace the
from apiflask import APIFlask app = APIFlask(__name__)
The key reasons behind making APIFlask a framework instead of a Flask extension is it makes possible to overwrite and change the internal behavior of Flask. For example:
Flask.dispatch_requestto ensure the natural order of the arguments injected into the view function (APIFlask 1.x).
- Add route shortcuts to the
Blueprintclass (added in Flask 2.0).
Flask.make_responseto support returning list as JSON response (added in Flask 2.2).
Flask.add_url_ruleto support generating OpenAPI spec for class-based views.
More automation for OpenAPI generating¶
- Add an auto-summary for the view function based on the name of view functions.
- Add success response (200) for a bare view function that only uses route decorators.
- Add validation error response (400) for view functions that use
- Add authentication error response (401) for view functions that use
- Add 404 response for view functions that contain URL variables.
- Add response schema for potential error responses of view function passed with
docdecorator. For example,
These automation behaviors can be changed with related configuration variables.
- Add a
docdecorator to allow set the OpenAPI spec for view functions in an explicit way.
- Support more OpenAPI fields (all fields from
- Support to customize the API documentation config and CDN URLs.
- Return JSON response for all HTTP errors and Auth errors as default.
- Class-based view support.