{"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":"python","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":[{"wrong":"from flask_apispec import FlaskApiSpec","symbol":"FlaskApiSpec","correct":"from flask_apispec import FlaskApiSpec"}],"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,"search_vec":"'0.11.4':38 'api':26,54 'apispec':3,6,13,45,56 'applic':18 'automat':20 'compat':49 'conveni':9 'current':35 'definit':30 'document':23,55 'flask':2,5,17,48,51 'flask-apispec':1,4 'follow':44 'generat':21 'infrequ':42 'integr':12 'layer':10 'marshal':33 'marshmallow':57 'often':43 'openapi':52 'openapi/swagger':22 'provid':7 'releas':40 'request/response':32 'requir':50 'rest':25 'schema':29 'simplifi':28 'swagger':53 'updat':46 'version':36 'webarg':58 'webargs/marshmallow':15","created_at":"2026-04-16T13:49:33.009145+00:00","updated_at":"2026-04-16T13:49:33.009145+00:00","problems":{"verify_error":"Traceback (most recent call last):\n  File \"<string>\", line 1, in <module>\n  File \"/tmp/tmp4jxp8x4l/venv/lib/python3.12/site-packages/flask_apispec/__init__.py\", line 1, in <module>\n    from flask_apispec.annotations import doc, marshal_with, use_kwargs, wrap_with\n  File \"/tmp/tmp4jxp8x4l/venv/lib/py"},"ecosystem":"pypi","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"0.11.4","cli_name":"","cli_version":null,"type":"library","homepage":null,"github":"https://github.com/jmcarp/flask-apispec","docs":null,"changelog":"https://flask-apispec.readthedocs.io/en/latest/changelog.html","pypi":"https://pypi.org/project/flask-apispec/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["web-framework","serialization","aws"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"import_fail","verified_at":"2026-07-03","last_verified":"2026-07-03","next_check":"2026-07-10","install_tag":null}}