Flask-Smorest

Warnings

• breaking As of v0.23.0, API title and version are mandatory parameters. They no longer default to `app.name` and `"1"` respectively. Attempting to initialize the API without these will raise an error.
  Fix: Set `API_TITLE` and `API_VERSION` in your Flask app configuration (e.g., `app.config["API_TITLE"] = "My API"`) or pass them directly when initializing `Api`.
• breaking In v0.24.0, Swagger UI configuration moved to a single `OPENAPI_SWAGGER_UI_CONFIG` dictionary. Old individual configuration parameters like `OPENAPI_SWAGGER_UI_SUPPORTED_SUBMIT_METHODS`, `layout`, and `deepLinking` were removed.
  Fix: Consolidate Swagger UI settings into a dictionary assigned to `app.config["OPENAPI_SWAGGER_UI_CONFIG"]`. For example, `app.config["OPENAPI_SWAGGER_UI_CONFIG"] = {"supportedSubmitMethods": ["get", "post"]}`.
• breaking Version 0.22.0 dropped support for Python 3.5. Subsequent versions require Python 3.6+ (and currently 3.10+ as of 0.47.0).
  Fix: Ensure your project is running on Python 3.10 or newer to use the latest versions of Flask-Smorest.
• breaking As of v0.21.0, Flask-Smorest dropped support for `webargs < 6.0.0`. If you have an older version of `webargs` pinned, this will cause dependency conflicts or runtime errors.
  Fix: Upgrade your `webargs` dependency to version 6.0.0 or higher (e.g., `pip install 'webargs>=6.0.0'`).
• breaking In v0.20.0, error component naming changed from `HTTPStatus.phrase` to `HTTPStatus.name` to avoid issues with spaces in URLs. Also, `DefaultError` was renamed to `DEFAULT_ERROR`.
  Fix: If you have custom error handlers or refer to these internal error names, update your code to use the new naming convention (`DEFAULT_ERROR` and `HTTPStatus.name`).
• gotcha Prior to v0.21.1, `apispec` (used internally by Flask-Smorest) could mutate documentation information dictionaries for view functions, especially when a single view served multiple HTTP methods. This could lead to incorrect or missing OpenAPI spec generation.
  Fix: Upgrade to Flask-Smorest v0.21.1 or newer. If stuck on an older version, ensure distinct documentation dictionaries are used or deep-copied for each method's specification.

Install

• pip install flask-smorest Install Flask-Smorest

Imports

• Api

  from flask_smorest import Api

• Blueprint

  from flask_smorest import Blueprint

• Schema

  from marshmallow import Schema

  Marshmallow Schema classes are imported directly from the `marshmallow` library, not `flask_smorest`.
• fields

  from marshmallow import fields

  Marshmallow fields are imported directly from the `marshmallow` library, not `flask_smorest`.

Quickstart

This quickstart sets up a basic Flask application with Flask-Smorest. It defines a simple `Item` resource with a Marshmallow schema, creates endpoints for listing, creating, and retrieving items, and exposes OpenAPI documentation via Swagger UI. Run this Flask app and navigate to `/docs/swagger-ui` to see the generated API documentation.

import os
from flask import Flask
from flask_smorest import Api, Blueprint
from marshmallow import Schema, fields

# 1. Basic Flask app setup
app = Flask(__name__)

# 2. Configuration for Flask-Smorest and OpenAPI
app.config["API_TITLE"] = "Simple Item API"
app.config["API_VERSION"] = "v1"
app.config["OPENAPI_VERSION"] = "3.0.2"
app.config["OPENAPI_URL_PREFIX"] = "/docs"
app.config["OPENAPI_SWAGGER_UI_PATH"] = "/swagger-ui"
app.config["SECRET_KEY"] = os.environ.get("FLASK_SECRET_KEY", "super-secret-key-development")

# 3. Initialize Flask-Smorest API
api = Api(app)

# 4. Define a Marshmallow Schema
class ItemSchema(Schema):
    id = fields.Integer(dump_only=True)
    name = fields.String(required=True)
    price = fields.Float(required=True)

# 5. Define a Blueprint
blp = Blueprint("items", __name__, url_prefix="/items", description="Operations on items")

# In-memory store for demonstration
items_db = {}
next_id = 1

# 6. Define API endpoints using the blueprint
@blp.route("/", methods=["POST"])
@blp.arguments(ItemSchema)
@blp.response(201, ItemSchema)
def create_item(new_item_data):
    """Create a new item"""
    global next_id
    new_item_data["id"] = next_id
    items_db[next_id] = new_item_data
    next_id += 1
    return new_item_data

@blp.route("/<int:item_id>", methods=["GET"])
@blp.response(200, ItemSchema)
def get_item(item_id):
    """Get an item by ID"""
    item = items_db.get(item_id)
    if item is None:
        return {"message": "Item not found"}, 404
    return item

@blp.route("/", methods=["GET"])
@blp.response(200, ItemSchema(many=True))
def get_all_items():
    """Get all items"""
    return list(items_db.values())

# 7. Register the blueprint with the API
api.register_blueprint(blp)

# Add a simple root route for testing if desired
@app.route("/")
def hello():
    return "Hello from Flask-Smorest API! Visit /docs/swagger-ui for API documentation."