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.
pip install flask-smorestVerified import paths — ran on the pinned version, not inferred.
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.
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`.
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"]}`.Ensure your project is running on Python 3.10 or newer to use the latest versions of Flask-Smorest.
Upgrade your `webargs` dependency to version 6.0.0 or higher (e.g., `pip install 'webargs>=6.0.0'`).
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`).
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 the package using pip: `pip install flask-smorest`.
Ensure `flask-smorest` is installed and import 'abort' as `from flask_smorest import abort`. If there's a conflict with `flask.abort`, alias them (e.g., `from flask import abort as flask_abort` and `from flask_smorest import abort as api_abort`).
Reorder the decorators so that the route decorator comes first, followed by `@blp.response`.
```python
# Incorrect
# @blp.response(200, PetSchema)
# @blp.route("/pets/<int:pet_id>")
# def get_pet(pet_id):
# pass
# Correct
@blp.route("/pets/<int:pet_id>")
@blp.response(200, PetSchema)
def get_pet(pet_id):
pass
```Use Flask's built-in converters for basic type validation in the route itself (e.g., `<int:pet_id>`). For more detailed path parameter documentation, use the `parameters` argument within `@blp.doc` or the `doc` parameter of `@blp.route`.
```python
# Incorrect (attempting to use a schema directly in route for path param)
# class PetIdSchema(ma.Schema):
# pet_id = ma.fields.Int(required=True, validate=lambda x: x > 0)
# @blp.route("/pets/<PetIdSchema:pet_id>") # This is not how schemas are used for path params
# def get_pet(pet_id):
# pass
# Correct (using Flask converter for type, and manual validation if needed)
@blp.route("/pets/<int:pet_id>")
@blp.response(200, PetSchema)
def get_pet(pet_id):
if pet_id <= 0:
abort(400, message="Pet ID must be positive")
# ... logic here
```