APISpec Web Framework Plugins

Warnings

• breaking 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.
  Fix: Change imports from `from apispec.ext.flask import FlaskPlugin` to `from apispec_webframeworks.flask import FlaskPlugin`.
• gotcha 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.
  Fix: Wrap calls to `spec.path()` in a `with app.test_request_context():` block or ensure a request context is active.
• gotcha 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.
  Fix: Install your desired web framework (e.g., `pip install flask`) alongside `apispec-webframeworks`.
• gotcha 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`.
  Fix: Use a community-maintained Starlette plugin (e.g., `starlette-apispec`) or implement custom integration.
• gotcha 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.
  Fix: For complex Flask Blueprint setups, investigate `flask-apispec` or `apispec-plugins`, or implement custom path registration within your Blueprints.

Install

• pip install apispec-webframeworks apispec[marshmallow] flask marshmallow Install with Flask and Marshmallow for quickstart
• pip install apispec-webframeworks Core library only

Imports

• FlaskPlugin

  from apispec_webframeworks.flask import FlaskPlugin

  Web framework plugins were moved from `apispec.ext` to `apispec_webframeworks` in `apispec` versions >= 1.0.0.
• AiohttpPlugin

  from apispec_webframeworks.aiohttp import AiohttpPlugin

• BottlePlugin

  from apispec_webframeworks.bottle import BottlePlugin

• TornadoPlugin

  from apispec_webframeworks.tornado import TornadoPlugin

Quickstart

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.

from flask import Flask
from apispec import APISpec
from apispec.ext.marshmallow import MarshmallowPlugin
from apispec_webframeworks.flask import FlaskPlugin
from marshmallow import Schema, fields

# 1. Create an APISpec instance
spec = APISpec(
    title="My Awesome API",
    version="1.0.0",
    openapi_version="3.0.2",
    info=dict(description="A minimal Flask API example"),
    plugins=[
        FlaskPlugin(),
        MarshmallowPlugin()
    ],
)

# 2. Define a Marshmallow Schema
class ItemSchema(Schema):
    id = fields.Int(dump_only=True)
    name = fields.Str(required=True, description="The item's name")

# 3. Register the schema with APISpec
spec.components.schema("Item", schema=ItemSchema)

# 4. Initialize Flask app
app = Flask(__name__)

# 5. Define a Flask route with OpenAPI docstrings
@app.route("/items/<int:item_id>")
def get_item(item_id):
    """Get item by ID
    ---
    parameters:
      - in: path
        name: item_id
        schema:
          type: integer
        required: true
        description: Numeric ID of the item to retrieve
    responses:
      200:
        description: Item details
        content:
          application/json:
            schema: ItemSchema
      404:
        description: Item not found
    """
    # In a real app, you'd fetch from a DB
    if item_id == 1:
        return ItemSchema().dump({'id': 1, 'name': 'Sample Item'})
    return {"message": "Item not found"}, 404

# 6. Register the Flask path with APISpec (must be in request context)
with app.test_request_context():
    spec.path(view=get_item)

# 7. Add an endpoint to serve the OpenAPI spec
@app.route("/swagger.json")
def swagger_spec():
    return spec.to_dict()

# To run this example:
# 1. Save as app.py
# 2. Run: flask run
# 3. Access: http://127.0.0.1:5000/swagger.json