{"id":3496,"library":"flask-smorest","title":"Flask-Smorest","description":"Flask-Smorest is a Flask/Marshmallow-based REST API framework that helps build documented REST APIs following the OpenAPI specification. It is currently at version 0.47.0 and maintains an active development pace with consistent minor and patch releases, primarily focusing on bug fixes and new features.","status":"active","version":"0.47.0","language":"en","source_language":"en","source_url":"https://github.com/marshmallow-code/flask-smorest","tags":["flask","rest-api","openapi","swagger","marshmallow","api-framework","documentation"],"install":[{"cmd":"pip install flask-smorest","lang":"bash","label":"Install Flask-Smorest"}],"dependencies":[{"reason":"Core web framework dependency.","package":"Flask"},{"reason":"Used for defining API schemas and data validation.","package":"marshmallow"},{"reason":"Used for parsing arguments from requests.","package":"webargs"},{"reason":"Used for generating OpenAPI specifications from code.","package":"apispec"},{"reason":"Used for pagination features.","package":"furl","optional":true},{"reason":"Required for `apispec[yaml]` to generate YAML OpenAPI specs.","package":"PyYAML","optional":true}],"imports":[{"symbol":"Api","correct":"from flask_smorest import Api"},{"symbol":"Blueprint","correct":"from flask_smorest import Blueprint"},{"note":"Marshmallow Schema classes are imported directly from the `marshmallow` library, not `flask_smorest`.","wrong":"from flask_smorest import Schema","symbol":"Schema","correct":"from marshmallow import Schema"},{"note":"Marshmallow fields are imported directly from the `marshmallow` library, not `flask_smorest`.","wrong":"from flask_smorest import fields","symbol":"fields","correct":"from marshmallow import fields"}],"quickstart":{"code":"import os\nfrom flask import Flask\nfrom flask_smorest import Api, Blueprint\nfrom marshmallow import Schema, fields\n\n# 1. Basic Flask app setup\napp = Flask(__name__)\n\n# 2. Configuration for Flask-Smorest and OpenAPI\napp.config[\"API_TITLE\"] = \"Simple Item API\"\napp.config[\"API_VERSION\"] = \"v1\"\napp.config[\"OPENAPI_VERSION\"] = \"3.0.2\"\napp.config[\"OPENAPI_URL_PREFIX\"] = \"/docs\"\napp.config[\"OPENAPI_SWAGGER_UI_PATH\"] = \"/swagger-ui\"\napp.config[\"SECRET_KEY\"] = os.environ.get(\"FLASK_SECRET_KEY\", \"super-secret-key-development\")\n\n# 3. Initialize Flask-Smorest API\napi = Api(app)\n\n# 4. Define a Marshmallow Schema\nclass ItemSchema(Schema):\n    id = fields.Integer(dump_only=True)\n    name = fields.String(required=True)\n    price = fields.Float(required=True)\n\n# 5. Define a Blueprint\nblp = Blueprint(\"items\", __name__, url_prefix=\"/items\", description=\"Operations on items\")\n\n# In-memory store for demonstration\nitems_db = {}\nnext_id = 1\n\n# 6. Define API endpoints using the blueprint\n@blp.route(\"/\", methods=[\"POST\"])\n@blp.arguments(ItemSchema)\n@blp.response(201, ItemSchema)\ndef create_item(new_item_data):\n    \"\"\"Create a new item\"\"\"\n    global next_id\n    new_item_data[\"id\"] = next_id\n    items_db[next_id] = new_item_data\n    next_id += 1\n    return new_item_data\n\n@blp.route(\"/<int:item_id>\", methods=[\"GET\"])\n@blp.response(200, ItemSchema)\ndef get_item(item_id):\n    \"\"\"Get an item by ID\"\"\"\n    item = items_db.get(item_id)\n    if item is None:\n        return {\"message\": \"Item not found\"}, 404\n    return item\n\n@blp.route(\"/\", methods=[\"GET\"])\n@blp.response(200, ItemSchema(many=True))\ndef get_all_items():\n    \"\"\"Get all items\"\"\"\n    return list(items_db.values())\n\n# 7. Register the blueprint with the API\napi.register_blueprint(blp)\n\n# Add a simple root route for testing if desired\n@app.route(\"/\")\ndef hello():\n    return \"Hello from Flask-Smorest API! Visit /docs/swagger-ui for API documentation.\"","lang":"python","description":"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."},"warnings":[{"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`.","message":"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.","severity":"breaking","affected_versions":">=0.23.0"},{"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\"]}`.","message":"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.","severity":"breaking","affected_versions":">=0.24.0"},{"fix":"Ensure your project is running on Python 3.10 or newer to use the latest versions of Flask-Smorest.","message":"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).","severity":"breaking","affected_versions":">=0.22.0"},{"fix":"Upgrade your `webargs` dependency to version 6.0.0 or higher (e.g., `pip install 'webargs>=6.0.0'`).","message":"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.","severity":"breaking","affected_versions":">=0.21.0"},{"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`).","message":"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`.","severity":"breaking","affected_versions":">=0.20.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":"<0.21.1"}],"env_vars":null,"last_verified":"2026-04-11T00:00:00.000Z","next_check":"2026-07-10T00:00:00.000Z"}