Install & Compatibility
Where this runs
tested against v0.11.4 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.940 runs
installs and imports cleanly · install 0.0s · import 0.000s · 33.6MB
glibcpy 3.10–3.940 runs
installs and imports cleanly · install 2.8s · import 0.000s · 34MB
32MB installed
● package 32MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
FlaskApiSpec
✓ from flask_apispec import FlaskApiSpec
✗ from flask_apispec import FlaskApiSpec
This quickstart demonstrates how to define a Marshmallow schema, apply `doc`, `use_kwargs`, and `marshal_with` decorators to Flask routes, and initialize `FlaskApiSpec` to generate OpenAPI documentation accessible via `/swagger-ui/`.
from flask import Flask, jsonify
from flask_apispec import doc, use_kwargs, marshal_with
from flask_apispec.extension import FlaskApiSpec
from marshmallow import Schema, fields
app = Flask(__name__)
app.config.update({
'APISPEC_SPEC': {
'title': 'My Awesome API',
'version': 'v1',
'openapi_version': '3.0.0' # Recommended for modern APIs
},
'APISPEC_SWAGGER_URL': '/swagger/',
'APISPEC_SWAGGER_UI_URL': '/swagger-ui/'
})
docs = FlaskApiSpec(app)
class ItemSchema(Schema):
id = fields.Int(dump_only=True)
name = fields.Str(required=True, description='Name of the item')
description = fields.Str(required=False, description='Description of the item')
items_db = {}
next_id = 1
@app.route('/items', methods=['POST'])
@doc(description='Create a new item', tags=['Items'])
@use_kwargs(ItemSchema, location='json')
@marshal_with(ItemSchema, code=201)
def create_item(**kwargs):
global next_id
item = kwargs
item['id'] = next_id
items_db[next_id] = item
next_id += 1
return jsonify(item), 201
@app.route('/items/<int:item_id>', methods=['GET'])
@doc(description='Get an item by ID', tags=['Items'], params={'item_id': {'description': 'Item ID', 'type': 'integer'}})
@marshal_with(ItemSchema, code=200)
def get_item(item_id):
item = items_db.get(item_id)
if item:
return jsonify(item), 200
return jsonify({'message': 'Item not found'}), 404
docs.register(create_item)
docs.register(get_item)
if __name__ == '__main__':
app.run(debug=True)
Debug
Known issues
breakingMajor version changes in `apispec` (e.g., v3 to v4, v4 to v5) introduce breaking changes, which `flask-apispec` eventually incorporates. Always check `apispec` release notes when upgrading, as `flask-apispec`'s `0.11.x` series is compatible with `apispec` 5.x.fixEnsure your `flask-apispec` version matches the compatible `apispec` version. For `apispec >= 5`, `FlaskApiSpec.register_converter` is a no-op; use `apispec.ext.marshmallow.MarshmallowPlugin` directly if needed.
affects: < 0.11.0 (for apispec < 5)
gotchaThe `openapi_version` in `APISPEC_SPEC` configuration (e.g., '2.0.0', '3.0.0', '3.1.0') significantly impacts the generated spec and supported features. `apispec` 5.x defaults to '3.0.0' or '3.1.0' but older examples might use '2.0.0'.fixExplicitly set `'openapi_version'` in your `APISPEC_SPEC` configuration to '3.0.0' or '3.1.0' for modern APIs. Ensure your schema definitions align with the chosen OpenAPI version.
affects: All versions
gotchaThe `doc` decorator's `params` argument structure for complex types or nested schemas can be tricky and requires careful mapping to OpenAPI specifications, often involving a `schema` key with a Marshmallow `Schema` instance.fixFor complex `params`, especially for request bodies, define a Marshmallow `Schema` and pass it via `schema=YourSchema`. For path/query/header parameters, ensure `type` and `description` are correctly specified, referring to the `apispec` documentation for exact structure.
affects: All versions
gotcha`use_kwargs` and `marshal_with` decorators require a `location` argument (e.g., `'json'`, `'query'`, `'headers'`, `'form'`) or a default configured via `APISPEC_DEFAULT_LOCATION` in `app.config`. Omitting it can lead to unexpected behavior or ignored parameters.fixAlways specify `location='json'` (or other appropriate location) for `use_kwargs` and `marshal_with` decorators, or set a global default in your Flask app config: `app.config['APISPEC_DEFAULT_LOCATION'] = 'json'`.
affects: All versions
Upgrade
Version history
0.11.4latest on PyPI · released Aug 11, 2022
Audit
Dependencies
flaskrequiredCore web framework.
apispecrequiredCore OpenAPI specification generator.
marshmallowoptionalRecommended schema definition and validation library. Installed via `[marshmallow]` extra.
webargsoptionalAlternative argument parsing and validation library. Installed via `[webargs]` extra.