APISpec

6.10.0 · active · verified Sun Apr 05

APISpec is a pluggable Python library designed for generating API specifications. It primarily supports the OpenAPI Specification (formerly known as the Swagger specification), enabling developers to programmatically define their API's structure, endpoints, and data models. It is framework-agnostic and offers built-in integration capabilities, notably with Marshmallow. The library maintains an active development status, with frequent patch and minor releases, and new major versions typically released on an annual or bi-annual cadence.

Warnings

breaking The `openapi_version` parameter in `APISpec` constructor is no longer optional and must be explicitly provided. It previously defaulted to '2.0'.
Fix: Always pass `openapi_version='2.0'` or `openapi_version='3.0.2'` (or another desired version) when initializing `APISpec`.
breaking Web framework integration plugins (e.g., for Flask, Bottle, Tornado) were moved from `apispec.ext` to a separate package, `apispec-webframeworks`.
Fix: Install `apispec-webframeworks` (`pip install apispec-webframeworks`) and update your import statements (e.g., `from apispec_webframeworks.flask import FlaskPlugin`).
breaking When referencing components (schemas, parameters, etc.), `apispec` now strictly requires referencing them by their ID, not their full path (e.g., use `'User'` instead of `#/definitions/User` or `#/components/schemas/User`).
Fix: Ensure all internal references to components within your spec are by their short ID. `apispec` will generate the correct full path based on the OpenAPI version.
breaking Support for Marshmallow 2.x was dropped. `apispec` now requires Marshmallow 3.13.0 or newer when using the Marshmallow plugin.
Fix: Upgrade your Marshmallow installation to a compatible version (e.g., `pip install -U 'marshmallow>=3.13.0'`). Consider using `apispec[marshmallow]` to ensure compatible versions are installed.
gotcha If you are creating custom `apispec` plugins, their helper methods must accept `**kwargs` in their signature, as `APISpec.path` may pass additional arguments.
Fix: Modify custom plugin helper method signatures to include `**kwargs` (e.g., `def my_helper(self, obj, **kwargs):`).
gotcha The `extra_fields` parameter for adding additional fields to schemas was removed. All fields should now be passed directly within the component dictionary.
Fix: Instead of `spec.components.schema('MySchema', schema=MySchema, extra_fields={'new_field': {'type': 'string'}}),` directly include all fields in your Marshmallow Schema or the component dictionary passed to `spec.components.schema`.

Install

pip install apispec Core library
pip install apispec[marshmallow] With Marshmallow plugin
pip install apispec[yaml] With YAML serialization support

Imports

APISpec
```
from apispec import APISpec
```

MarshmallowPlugin

from apispec.ext.marshmallow import MarshmallowPlugin

FlaskPlugin
```
from apispec_webframeworks.flask import FlaskPlugin
```
Web framework plugins like FlaskPlugin were moved to the `apispec-webframeworks` package in APISpec 1.0.0 and later.

Quickstart

This quickstart demonstrates how to initialize an `APISpec` object, define a Marshmallow schema, register it as an OpenAPI component, and then add a path with an operation that references the defined schema. Finally, it prints the generated OpenAPI specification in JSON format. This illustrates the basic programmatic API definition workflow using `apispec` and its Marshmallow plugin.

from apispec import APISpec
from apispec.ext.marshmallow import MarshmallowPlugin
from marshmallow import Schema, fields
import json

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

# 2. Define a Marshmallow Schema and register it as an OpenAPI component
class UserSchema(Schema):
    id = fields.Int(dump_only=True)
    name = fields.Str(required=True, description="The user's name")
    email = fields.Email(required=True, description="The user's email address")

spec.components.schema("User", schema=UserSchema)

# 3. Add a path with operations referencing the schema
spec.path(
    path="/users/{user_id}",
    operations=dict(
        get=dict(
            summary="Get user by ID",
            parameters=[
                {
                    "in": "path",
                    "name": "user_id",
                    "schema": {"type": "integer"},
                    "required": True,
                    "description": "Numeric ID of the user to get",
                }
            ],
            responses={
                200: {
                    "description": "User data",
                    "content": {"application/json": {"schema": {"$ref": "#/components/schemas/User"}}},
                }
            },
        )
    ),
)

# 4. Output the spec as JSON
print(json.dumps(spec.to_dict(), indent=2))

view raw JSON →