APIFlask

3.1.0 verified Thu Apr 16 auth: no python

APIFlask is a lightweight Python web API framework built on top of Flask. It enhances Flask with modern API features such as automatic request validation, response formatting, OpenAPI specification generation, and interactive API documentation (Swagger UI, Redoc, Elements, etc.). It is ORM/ODM-agnostic and offers flexible data schema support through both Marshmallow schemas and Pydantic models. The current stable version is 3.1.0, and it maintains an active release cadence, closely following Flask's development.

pip install apiflask

Common errors

error ModuleNotFoundError: No module named 'apiflask' ↓

cause The `apiflask` library is not installed in the current Python environment.

fix

Run pip install apiflask to install the library.

error TypeError: The view function did not return a valid response. The return type must be a string, dict, tuple, Response instance, or WSGI callable. ↓

cause Your view function returned a complex object (e.g., a custom class instance) without an `@app.output()` decorator to serialize it, or the object is not a simple dictionary/list that Flask can convert to JSON.

fix

Decorate your view function with @app.output(YourSchema) to define how the return value should be serialized to JSON. If returning a non-dict, ensure it's explicitly handled or convertible.

error werkzeug.exceptions.UnprocessableEntity: 422 Unprocessable Entity ↓

cause This error (or similar `ValidationError` from Marshmallow/Pydantic) indicates that the request payload did not conform to the schema defined in the `@app.input()` decorator.

fix

Check the API documentation for the expected input schema and ensure your request body or query parameters match it. The error response details will typically provide specifics on validation failures.

error AttributeError: 'HTTPTokenAuth' object has no attribute 'verify_apikey' (or similar auth-related AttributeError) ↓

cause You are likely using `HTTPTokenAuth` for API key authentication on APIFlask v3.x or later, which has been deprecated and refactored.

fix

Migrate your API key authentication to use APIKeyHeaderAuth, APIKeyCookieAuth, or APIKeyQueryAuth from apiflask.security.

error RuntimeError: 'APIFlask' object has no attribute 'json_errors' when trying to configure JSON error handling (or similar configuration issues) ↓

cause Accessing or setting configuration variables incorrectly, or attempting to configure features that have been renamed or refactored in newer versions.

fix

Consult the APIFlask documentation for the current version's configuration variables and their correct usage. Some settings might have moved or been replaced by APIFlask constructor arguments or specific decorators.

Warnings

breaking APIFlask 3.x refactored API key authentication. Old classes like `HTTPTokenAuth` are deprecated for API keys. Instead, use `APIKeyHeaderAuth`, `APIKeyCookieAuth`, or `APIKeyQueryAuth` based on the key's location. ↓

fix Update your authentication logic to import and use the new `security.APIKey*Auth` classes from `apiflask.security` and configure them appropriately.

breaking APIFlask 3.x dropped official support for Python 3.8 and PyPy 3.10. While it might still work, new features and fixes are not guaranteed for these versions. ↓

fix Upgrade your Python environment to Python 3.9 or newer.

breaking In APIFlask 2.x, data passed via the `@app.input()` decorator is now injected into the view function as a keyword argument named `{location}_data` (e.g., `json_data`, `query_data`). ↓

fix Adjust your view function signatures to accept the input data as a keyword argument, e.g., `def create_pet(json_data):`.

gotcha APIFlask's `abort()` function (`from apiflask import abort`) automatically returns a JSON error response, which differs from Flask's default `flask.abort()` behavior (which typically returns HTML). ↓

fix Always import `abort` from `apiflask` when you intend to return structured JSON errors. Be aware that if `app.json_errors` is True (default), Flask's `flask.abort` will also return JSON error responses, but `apiflask.abort` offers more control.

gotcha When using Pydantic models for output validation with `@app.output()`, if the data returned by your view function does not conform to the specified Pydantic model, APIFlask will raise a `500 Internal Server Error` before sending the response. ↓

fix Ensure that the data returned by your view functions strictly matches the defined Pydantic output model. Implement thorough testing of your output serialization.

breaking APIFlask 1.2.0 introduced a breaking change where `apiflask.views.MethodView` must be used for class-based views instead of `flask.views.MethodView` to ensure proper OpenAPI spec generation and functionality. ↓

fix Import `MethodView` from `apiflask.views` for your class-based views, e.g., `from apiflask.views import MethodView`.

breaking The default status code for request validation errors changed from `400 Bad Request` to `422 Unprocessable Entity` in APIFlask 1.2.0, aligning with common API practices for semantic validation errors. ↓

fix Update client-side error handling to expect `422` for input validation failures.

Imports

APIFlask
```
from apiflask import APIFlask
```
APIBlueprint
wrong
```
from flask import Blueprint
```
correct
```
from apiflask import APIBlueprint
```
Use APIBlueprint for OpenAPI-enabled blueprints instead of Flask's Blueprint.
abort
wrong
```
from flask import abort
```
correct
```
from apiflask import abort
```
APIFlask's abort returns JSON error responses by default, unlike Flask's.
HTTPError
```
from apiflask import HTTPError
```
Schema
```
from apiflask import Schema
```
For Marshmallow schemas. Fields like `String`, `Integer` are also imported from `apiflask.fields`.
BaseModel
```
from pydantic import BaseModel
```
For Pydantic models, requires pydantic to be installed.

Quickstart

This quickstart initializes an APIFlask application, defines a simple Marshmallow schema for responses, and sets up a GET endpoint that returns a JSON message. APIFlask automatically generates OpenAPI documentation available at `/docs` by default.

from apiflask import APIFlask
from apiflask.fields import String
from apiflask.schemas import Schema

app = APIFlask(__name__, title='My Awesome API', version='1.0.0')

class MessageSchema(Schema):
    message = String(required=True, example='Hello from APIFlask')

@app.get('/')
@app.output(MessageSchema)
def index():
    return {'message': 'Hello from APIFlask'}

# To run: flask --app your_app_file_name run