{"id":6990,"library":"apiflask","title":"APIFlask","description":"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.","status":"active","version":"3.1.0","language":"en","source_language":"en","source_url":"https://github.com/apiflask/apiflask","tags":["flask","api","openapi","swagger","marshmallow","pydantic","web-framework","rest"],"install":[{"cmd":"pip install apiflask","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Required for execution","package":"Python","version":">=3.9"},{"reason":"Core web framework dependency","package":"Flask","version":">=2.1"},{"reason":"Default data validation and serialization library","package":"marshmallow","optional":true},{"reason":"Alternative data validation and serialization library (v3.x+)","package":"pydantic","optional":true}],"imports":[{"symbol":"APIFlask","correct":"from apiflask import APIFlask"},{"note":"Use APIBlueprint for OpenAPI-enabled blueprints instead of Flask's Blueprint.","wrong":"from flask import Blueprint","symbol":"APIBlueprint","correct":"from apiflask import APIBlueprint"},{"note":"APIFlask's abort returns JSON error responses by default, unlike Flask's.","wrong":"from flask import abort","symbol":"abort","correct":"from apiflask import abort"},{"symbol":"HTTPError","correct":"from apiflask import HTTPError"},{"note":"For Marshmallow schemas. Fields like `String`, `Integer` are also imported from `apiflask.fields`.","symbol":"Schema","correct":"from apiflask import Schema"},{"note":"For Pydantic models, requires pydantic to be installed.","symbol":"BaseModel","correct":"from pydantic import BaseModel"}],"quickstart":{"code":"from apiflask import APIFlask\nfrom apiflask.fields import String\nfrom apiflask.schemas import Schema\n\napp = APIFlask(__name__, title='My Awesome API', version='1.0.0')\n\nclass MessageSchema(Schema):\n    message = String(required=True, example='Hello from APIFlask')\n\n@app.get('/')\n@app.output(MessageSchema)\ndef index():\n    return {'message': 'Hello from APIFlask'}\n\n# To run: flask --app your_app_file_name run","lang":"python","description":"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."},"warnings":[{"fix":"Update your authentication logic to import and use the new `security.APIKey*Auth` classes from `apiflask.security` and configure them appropriately.","message":"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.","severity":"breaking","affected_versions":"3.0.0 and later"},{"fix":"Upgrade your Python environment to Python 3.9 or newer.","message":"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.","severity":"breaking","affected_versions":"3.0.0 and later"},{"fix":"Adjust your view function signatures to accept the input data as a keyword argument, e.g., `def create_pet(json_data):`.","message":"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`).","severity":"breaking","affected_versions":"2.0.0 and later"},{"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.","message":"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).","severity":"gotcha","affected_versions":"All versions"},{"fix":"Ensure that the data returned by your view functions strictly matches the defined Pydantic output model. Implement thorough testing of your output serialization.","message":"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.","severity":"gotcha","affected_versions":"3.0.0 and later (when using Pydantic)"},{"fix":"Import `MethodView` from `apiflask.views` for your class-based views, e.g., `from apiflask.views import MethodView`.","message":"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.","severity":"breaking","affected_versions":"1.2.0 and later"},{"fix":"Update client-side error handling to expect `422` for input validation failures.","message":"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.","severity":"breaking","affected_versions":"1.2.0 and later"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Run `pip install apiflask` to install the library.","cause":"The `apiflask` library is not installed in the current Python environment.","error":"ModuleNotFoundError: No module named 'apiflask'"},{"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.","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.","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."},{"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.","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.","error":"werkzeug.exceptions.UnprocessableEntity: 422 Unprocessable Entity"},{"fix":"Migrate your API key authentication to use `APIKeyHeaderAuth`, `APIKeyCookieAuth`, or `APIKeyQueryAuth` from `apiflask.security`.","cause":"You are likely using `HTTPTokenAuth` for API key authentication on APIFlask v3.x or later, which has been deprecated and refactored.","error":"AttributeError: 'HTTPTokenAuth' object has no attribute 'verify_apikey' (or similar auth-related AttributeError)"},{"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.","cause":"Accessing or setting configuration variables incorrectly, or attempting to configure features that have been renamed or refactored in newer versions.","error":"RuntimeError: 'APIFlask' object has no attribute 'json_errors' when trying to configure JSON error handling (or similar configuration issues)"}]}