{"id":7235,"library":"flask-apispec","title":"Flask-APISpec","description":"Flask-APISpec provides a convenient layer for integrating APISpec and webargs/marshmallow with Flask applications to automatically generate OpenAPI/Swagger documentation for REST APIs. It simplifies schema definition and request/response marshaling. The current version is 0.11.4, and releases are infrequent, often following `apispec` updates or Flask compatibility requirements.","status":"active","version":"0.11.4","language":"en","source_language":"en","source_url":"https://github.com/jmcarp/flask-apispec","tags":["flask","openapi","swagger","api documentation","apispec","marshmallow","webargs"],"install":[{"cmd":"pip install flask-apispec[marshmallow]","lang":"bash","label":"Recommended installation with Marshmallow"},{"cmd":"pip install flask-apispec[webargs]","lang":"bash","label":"Alternative installation with Webargs"}],"dependencies":[{"reason":"Core web framework.","package":"flask","optional":false},{"reason":"Core OpenAPI specification generator.","package":"apispec","optional":false},{"reason":"Recommended schema definition and validation library. Installed via `[marshmallow]` extra.","package":"marshmallow","optional":true},{"reason":"Alternative argument parsing and validation library. Installed via `[webargs]` extra.","package":"webargs","optional":true}],"imports":[{"symbol":"FlaskApiSpec","correct":"from flask_apispec.extension import FlaskApiSpec"},{"symbol":"doc","correct":"from flask_apispec import doc"},{"symbol":"use_kwargs","correct":"from flask_apispec import use_kwargs"},{"symbol":"marshal_with","correct":"from flask_apispec import marshal_with"},{"symbol":"MethodResource","correct":"from flask_apispec.views import MethodResource"}],"quickstart":{"code":"from flask import Flask, jsonify\nfrom flask_apispec import doc, use_kwargs, marshal_with\nfrom flask_apispec.extension import FlaskApiSpec\nfrom marshmallow import Schema, fields\n\napp = Flask(__name__)\napp.config.update({\n    'APISPEC_SPEC': {\n        'title': 'My Awesome API',\n        'version': 'v1',\n        'openapi_version': '3.0.0' # Recommended for modern APIs\n    },\n    'APISPEC_SWAGGER_URL': '/swagger/',\n    'APISPEC_SWAGGER_UI_URL': '/swagger-ui/'\n})\ndocs = FlaskApiSpec(app)\n\nclass ItemSchema(Schema):\n    id = fields.Int(dump_only=True)\n    name = fields.Str(required=True, description='Name of the item')\n    description = fields.Str(required=False, description='Description of the item')\n\nitems_db = {}\nnext_id = 1\n\n@app.route('/items', methods=['POST'])\n@doc(description='Create a new item', tags=['Items'])\n@use_kwargs(ItemSchema, location='json')\n@marshal_with(ItemSchema, code=201)\ndef create_item(**kwargs):\n    global next_id\n    item = kwargs\n    item['id'] = next_id\n    items_db[next_id] = item\n    next_id += 1\n    return jsonify(item), 201\n\n@app.route('/items/<int:item_id>', methods=['GET'])\n@doc(description='Get an item by ID', tags=['Items'], params={'item_id': {'description': 'Item ID', 'type': 'integer'}})\n@marshal_with(ItemSchema, code=200)\ndef get_item(item_id):\n    item = items_db.get(item_id)\n    if item: \n        return jsonify(item), 200\n    return jsonify({'message': 'Item not found'}), 404\n\ndocs.register(create_item)\ndocs.register(get_item)\n\nif __name__ == '__main__':\n    app.run(debug=True)\n","lang":"python","description":"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/`."},"warnings":[{"fix":"Ensure 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.","message":"Major 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.","severity":"breaking","affected_versions":"< 0.11.0 (for apispec < 5)"},{"fix":"Explicitly 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.","message":"The `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'.","severity":"gotcha","affected_versions":"All versions"},{"fix":"For 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.","message":"The `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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Always 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'`.","message":"`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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Ensure `flask-apispec` is installed with its necessary dependencies, e.g., `pip install flask-apispec[marshmallow]`.","cause":"Flask-APISpec is not installed or installed incorrectly, likely missing the `[marshmallow]` or `[webargs]` extras.","error":"ModuleNotFoundError: No module named 'flask_apispec.extension'"},{"fix":"Review your `@doc` decorator arguments and Marshmallow schema fields to ensure all string-expected values are actual strings and not `None`.","cause":"A `doc` decorator argument (like `description`) or a schema field expects a string but received `None`, which Flask or `apispec` cannot process.","error":"TypeError: can only concatenate str (not NoneType) to str"},{"fix":"This method is now a no-op within `flask-apispec` when `apispec >= 5.0` is detected. If you were using it for custom schema types, you might need to integrate a custom `Plugin` with `apispec` directly, or ensure `apispec.ext.marshmallow.MarshmallowPlugin` is used correctly if registering Marshmallow fields.","cause":"This error typically occurs when `flask-apispec` is used with `apispec >= 5.0`, which removed the `register_converter` method from `APISpec`.","error":"AttributeError: 'APISpec' object has no attribute 'register_converter'"},{"fix":"For complex parameters, define a Marshmallow `Schema` and pass it to the `schema` key in the `@doc` decorator's `params` or `requestBody` definition. Example: `@doc(requestBody={'content': {'application/json': {'schema': ItemSchema}}})`.","cause":"When defining parameters for the `@doc` decorator, especially for `requestBody`, `flask-apispec` and `apispec` expect a schema reference (e.g., `schema=YourSchema`) rather than a simple dictionary or missing schema definition.","error":"Validation Error: 'schema' is a required property"}]}