APIFlask

Common errors

• 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.

• 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.

• 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.

• 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`.

• 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.

Install

• pip install apiflask Install stable version

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