{"id":5851,"library":"apispec-webframeworks","title":"APISpec Web Framework Plugins","description":"apispec-webframeworks is a Python library providing plugins to integrate `apispec` with various web frameworks like Flask, Aiohttp, Bottle, and Tornado. These plugins were originally part of `apispec.ext` but were moved to this separate package to streamline `apispec`'s core. It is currently at version 1.2.0 and receives updates to maintain compatibility with `apispec` and relevant frameworks.","status":"active","version":"1.2.0","language":"en","source_language":"en","source_url":"https://github.com/marshmallow-code/apispec-webframeworks","tags":["API specification","OpenAPI","Swagger","Flask","Aiohttp","Bottle","Tornado","web framework","plugins","marshmallow"],"install":[{"cmd":"pip install apispec-webframeworks apispec[marshmallow] flask marshmallow","lang":"bash","label":"Install with Flask and Marshmallow for quickstart"},{"cmd":"pip install apispec-webframeworks","lang":"bash","label":"Core library only"}],"dependencies":[{"reason":"This library provides plugins for apispec.","package":"apispec","optional":false},{"reason":"Required to use the FlaskPlugin. Not installed by apispec-webframeworks itself.","package":"flask","optional":true},{"reason":"Required to use the AiohttpPlugin. Not installed by apispec-webframeworks itself.","package":"aiohttp","optional":true},{"reason":"Required to use the BottlePlugin. Not installed by apispec-webframeworks itself.","package":"bottle","optional":true},{"reason":"Required to use the TornadoPlugin. Not installed by apispec-webframeworks itself.","package":"tornado","optional":true},{"reason":"Commonly used with apispec for schema generation, especially via `apispec.ext.marshmallow.MarshmallowPlugin`.","package":"marshmallow","optional":true}],"imports":[{"note":"Web framework plugins were moved from `apispec.ext` to `apispec_webframeworks` in `apispec` versions >= 1.0.0.","wrong":"from apispec.ext.flask import FlaskPlugin","symbol":"FlaskPlugin","correct":"from apispec_webframeworks.flask import FlaskPlugin"},{"symbol":"AiohttpPlugin","correct":"from apispec_webframeworks.aiohttp import AiohttpPlugin"},{"symbol":"BottlePlugin","correct":"from apispec_webframeworks.bottle import BottlePlugin"},{"symbol":"TornadoPlugin","correct":"from apispec_webframeworks.tornado import TornadoPlugin"}],"quickstart":{"code":"from flask import Flask\nfrom apispec import APISpec\nfrom apispec.ext.marshmallow import MarshmallowPlugin\nfrom apispec_webframeworks.flask import FlaskPlugin\nfrom marshmallow import Schema, fields\n\n# 1. Create an APISpec instance\nspec = APISpec(\n    title=\"My Awesome API\",\n    version=\"1.0.0\",\n    openapi_version=\"3.0.2\",\n    info=dict(description=\"A minimal Flask API example\"),\n    plugins=[\n        FlaskPlugin(),\n        MarshmallowPlugin()\n    ],\n)\n\n# 2. Define a Marshmallow Schema\nclass ItemSchema(Schema):\n    id = fields.Int(dump_only=True)\n    name = fields.Str(required=True, description=\"The item's name\")\n\n# 3. Register the schema with APISpec\nspec.components.schema(\"Item\", schema=ItemSchema)\n\n# 4. Initialize Flask app\napp = Flask(__name__)\n\n# 5. Define a Flask route with OpenAPI docstrings\n@app.route(\"/items/<int:item_id>\")\ndef get_item(item_id):\n    \"\"\"Get item by ID\n    ---\n    parameters:\n      - in: path\n        name: item_id\n        schema:\n          type: integer\n        required: true\n        description: Numeric ID of the item to retrieve\n    responses:\n      200:\n        description: Item details\n        content:\n          application/json:\n            schema: ItemSchema\n      404:\n        description: Item not found\n    \"\"\"\n    # In a real app, you'd fetch from a DB\n    if item_id == 1:\n        return ItemSchema().dump({'id': 1, 'name': 'Sample Item'})\n    return {\"message\": \"Item not found\"}, 404\n\n# 6. Register the Flask path with APISpec (must be in request context)\nwith app.test_request_context():\n    spec.path(view=get_item)\n\n# 7. Add an endpoint to serve the OpenAPI spec\n@app.route(\"/swagger.json\")\ndef swagger_spec():\n    return spec.to_dict()\n\n# To run this example:\n# 1. Save as app.py\n# 2. Run: flask run\n# 3. Access: http://127.0.0.1:5000/swagger.json\n","lang":"python","description":"This quickstart demonstrates how to integrate `apispec-webframeworks` with Flask and `marshmallow` to automatically generate OpenAPI specifications from view function docstrings and Marshmallow schemas. It sets up a basic Flask application, defines an API endpoint, and exposes the generated OpenAPI JSON."},"warnings":[{"fix":"Change imports from `from apispec.ext.flask import FlaskPlugin` to `from apispec_webframeworks.flask import FlaskPlugin`.","message":"The web framework plugins (e.g., `FlaskPlugin`, `AiohttpPlugin`) were moved from `apispec.ext` to the dedicated `apispec-webframeworks` package. If upgrading `apispec` from a version older than `1.0.0`, you must update your imports.","severity":"breaking","affected_versions":"< 1.0.0 (for apispec) / all (for apispec-webframeworks)"},{"fix":"Wrap calls to `spec.path()` in a `with app.test_request_context():` block or ensure a request context is active.","message":"When using `spec.path(view=...)` for Flask views, the call must be made within an active Flask application context or a `test_request_context` for `apispec` to correctly inspect the view and its route.","severity":"gotcha","affected_versions":"all"},{"fix":"Install your desired web framework (e.g., `pip install flask`) alongside `apispec-webframeworks`.","message":"This library provides *plugins* for web frameworks but does not install the frameworks themselves. You must explicitly install your chosen web framework (e.g., `flask`, `aiohttp`, `bottle`, `tornado`) separately.","severity":"gotcha","affected_versions":"all"},{"fix":"Use a community-maintained Starlette plugin (e.g., `starlette-apispec`) or implement custom integration.","message":"As of version 1.2.0, `apispec-webframeworks` does not officially provide a plugin for Starlette. If you are looking for Starlette integration, consider alternative packages like `starlette-apispec` or `apispec-plugins`.","severity":"gotcha","affected_versions":"all"},{"fix":"For complex Flask Blueprint setups, investigate `flask-apispec` or `apispec-plugins`, or implement custom path registration within your Blueprints.","message":"Support for Flask Blueprints within `apispec-webframeworks.flask.FlaskPlugin` may be limited, potentially requiring manual workarounds or alternative libraries like `flask-apispec` or `apispec-plugins` for full integration. There are open discussions about enhancing this.","severity":"gotcha","affected_versions":"all"}],"env_vars":null,"last_verified":"2026-04-14T00:00:00.000Z","next_check":"2026-07-13T00:00:00.000Z"}