{"id":1086,"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":"python","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. Additionally, update your Marshmallow schemas to use syntax compatible with Marshmallow 3.x/4.x (e.g., replace `fields.Str(description=...)` with `fields.Str(metadata={'description': '...'})` and similar adjustments for other removed arguments like `allow_none`).","message":"Support for Marshmallow 2.x was dropped. `apispec` now requires Marshmallow 3.13.0 or newer when using the Marshmallow plugin. This includes significant API changes in Marshmallow 3.x/4.x, such as the removal of the `description` parameter from field constructors.","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"},{"fix":"Update your Marshmallow schema definitions to be compatible with Marshmallow 4.x. For example, change `fields.Str(description='...')` to `fields.Str(metadata={'description': '...'})` and `fields.Str(example='...')` to `fields.Str(metadata={'example': '...'})`. Alternatively, pin your Marshmallow version to `<4.0.0` (e.g., `marshmallow>=3.18.0,<4.0.0`) if you are unable to update your schema definitions.","message":"Marshmallow 4.x introduced breaking changes to `marshmallow.fields`, notably removing direct `description` and `example` arguments from field constructors. If `apispec`'s dependency range (e.g., `marshmallow>=3.18.0` for `apispec>=6.0.0`) installs Marshmallow 4.x, your schemas written for Marshmallow 3.x will raise a `TypeError` for these arguments.","severity":"breaking","affected_versions":">=6.0.0"}],"env_vars":null,"search_vec":"'activ':57 'agnost':42 'annual':74,78 'api':11,31,80 'apispec':1,2 'bi':77 'bi-annu':76 'built':46 'built-in':45 'cadenc':79 'capabl':49 'data':36 'defin':29 'design':8 'develop':26,58 'document':84 'enabl':25 'endpoint':34 'former':19 'framework':41 'framework-agnost':40 'frequent':61 'generat':10 'integr':48 'known':20 'librari':7,54 'maintain':55 'major':68 'marshmallow':52,86 'minor':64 'model':37 'new':67 'notabl':50 'offer':44 'openapi':17,81 'patch':62 'pluggabl':5 'primarili':14 'programmat':28 'python':6 'releas':65,71 'rest':85 'specif':12,18,24,83 'status':59 'structur':33 'support':15 'swagger':23,82 'typic':70 'version':69","created_at":"2026-04-05T13:05:06.208240+00:00","updated_at":"2026-04-15T20:46:46.968736+00:00","problems":[{"fix":"Ensure that each operation in your OpenAPI specification includes a 'responses' field with appropriate response definitions.","cause":"The OpenAPI specification is missing the 'responses' field in the operation definition.","error":"openapi_spec_validator.exceptions.OpenAPIValidationError: 'responses' is a required property"},{"fix":"Use unique names for each component when registering them in the specification.","cause":"Attempting to register a component with a name that has already been used in the specification.","error":"apispec.exceptions.DuplicateComponentNameError: Component name 'ExampleComponent' is already registered"},{"fix":"Ensure that all parameter definitions include the 'name', 'in', and 'schema' keys with appropriate values.","cause":"A parameter definition is missing one or more required keys: 'name', 'in', or 'schema'.","error":"apispec.exceptions.InvalidParameterError: Parameter must contain required keys: 'name', 'in', 'schema'"},{"fix":"Implement the required method in your plugin or avoid calling unimplemented methods.","cause":"A plugin method is being called that has not been implemented in the plugin.","error":"apispec.exceptions.PluginMethodNotImplementedError: Plugin method 'example_method' not implemented"},{"fix":"Validate your OpenAPI specification against the OpenAPI standard and correct any validation errors.","cause":"The generated OpenAPI specification does not conform to the OpenAPI standard.","error":"apispec.exceptions.OpenAPIError: OpenAPI spec validation failed"}],"ecosystem":"pypi","meta_description":null,"install_score":100,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"6.10.0","cli_name":"","cli_version":null,"type":"library","homepage":"https://apispec.readthedocs.io/","github":"https://github.com/marshmallow-code/apispec","docs":null,"changelog":"https://apispec.readthedocs.io/en/latest/changelog.html","pypi":"https://pypi.org/project/apispec/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["serialization","web-framework","http-networking"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-06-28","last_verified":"2026-06-28","next_check":"2026-07-28","install_tag":"verified"}}