{"library":"apispec","title":"APISpec","description":"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.","status":"active","version":"6.10.0","language":"en","source_language":"en","source_url":"https://github.com/marshmallow-code/apispec","tags":["api","openapi","swagger","specification","documentation","rest","marshmallow"],"install":[{"cmd":"pip install apispec","lang":"bash","label":"Core library"},{"cmd":"pip install apispec[marshmallow]","lang":"bash","label":"With Marshmallow plugin"},{"cmd":"pip install apispec[yaml]","lang":"bash","label":"With YAML serialization support"}],"dependencies":[{"reason":"Required Python version","package":"python","version":">=3.10","optional":false},{"reason":"Dependency for core functionality","package":"packaging","version":">=21.3","optional":false},{"reason":"Required for apispec.ext.marshmallow plugin","package":"marshmallow","version":">=3.18.0","optional":true},{"reason":"Required for YAML serialization (apispec[yaml] extra)","package":"pyyaml","version":">=3.10","optional":true}],"imports":[{"symbol":"APISpec","correct":"from apispec import APISpec"},{"symbol":"MarshmallowPlugin","correct":"from apispec.ext.marshmallow import MarshmallowPlugin"},{"note":"Web framework plugins like FlaskPlugin were moved to the `apispec-webframeworks` package in APISpec 1.0.0 and later.","wrong":"from apispec.ext.flask import FlaskPlugin","symbol":"FlaskPlugin","correct":"from apispec_webframeworks.flask import FlaskPlugin"}],"quickstart":{"code":"from apispec import APISpec\nfrom apispec.ext.marshmallow import MarshmallowPlugin\nfrom marshmallow import Schema, fields\nimport json\n\n# 1. Create an APISpec object\nspec = APISpec(\n    title=\"My Awesome API\",\n    version=\"1.0.0\",\n    openapi_version=\"3.0.2\",\n    info=dict(description=\"A minimal example of APISpec\"),\n    plugins=[\n        MarshmallowPlugin(),\n    ],\n)\n\n# 2. Define a Marshmallow Schema and register it as an OpenAPI component\nclass UserSchema(Schema):\n    id = fields.Int(dump_only=True)\n    name = fields.Str(required=True, description=\"The user's name\")\n    email = fields.Email(required=True, description=\"The user's email address\")\n\nspec.components.schema(\"User\", schema=UserSchema)\n\n# 3. Add a path with operations referencing the schema\nspec.path(\n    path=\"/users/{user_id}\",\n    operations=dict(\n        get=dict(\n            summary=\"Get user by ID\",\n            parameters=[\n                {\n                    \"in\": \"path\",\n                    \"name\": \"user_id\",\n                    \"schema\": {\"type\": \"integer\"},\n                    \"required\": True,\n                    \"description\": \"Numeric ID of the user to get\",\n                }\n            ],\n            responses={\n                200: {\n                    \"description\": \"User data\",\n                    \"content\": {\"application/json\": {\"schema\": {\"$ref\": \"#/components/schemas/User\"}}},\n                }\n            },\n        )\n    ),\n)\n\n# 4. Output the spec as JSON\nprint(json.dumps(spec.to_dict(), indent=2))","lang":"python","description":"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."},"warnings":[{"fix":"Always pass `openapi_version='2.0'` or `openapi_version='3.0.2'` (or another desired version) when initializing `APISpec`.","message":"The `openapi_version` parameter in `APISpec` constructor is no longer optional and must be explicitly provided. It previously defaulted to '2.0'.","severity":"breaking","affected_versions":">=1.0.0"},{"fix":"Install `apispec-webframeworks` (`pip install apispec-webframeworks`) and update your import statements (e.g., `from apispec_webframeworks.flask import FlaskPlugin`).","message":"Web framework integration plugins (e.g., for Flask, Bottle, Tornado) were moved from `apispec.ext` to a separate package, `apispec-webframeworks`.","severity":"breaking","affected_versions":">=1.0.0"},{"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.","message":"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`).","severity":"breaking","affected_versions":">=2.0.0"},{"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.","message":"Support for Marshmallow 2.x was dropped. `apispec` now requires Marshmallow 3.13.0 or newer when using the Marshmallow plugin.","severity":"breaking","affected_versions":">=4.0.0"},{"fix":"Modify custom plugin helper method signatures to include `**kwargs` (e.g., `def my_helper(self, obj, **kwargs):`).","message":"If you are creating custom `apispec` plugins, their helper methods must accept `**kwargs` in their signature, as `APISpec.path` may pass additional arguments.","severity":"gotcha","affected_versions":">=2.0.0"},{"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`.","message":"The `extra_fields` parameter for adding additional fields to schemas was removed. All fields should now be passed directly within the component dictionary.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-05T00:00:00.000Z","next_check":"2026-07-04T00:00:00.000Z"}