apispec

Features:

• apispec.core.Components is added. Each APISpec instance has a Components object used to define components such as schemas, parameters or responses. "Components" is the OpenAPI v3 terminology for those reusable top-level objects.

• apispec.core.Components.parameter and apispec.core.Components.response are added.

• Backwards-incompatible: apispec.APISpec.add_path and apispec.APISpec.add_tag are renamed to apispec.APISpec.path and apispec.APISpec.tag.

• Backwards-incompatible: apispec.APISpec.definition is moved to the Components class and renamed to apispec.core.Components.schema.

# apispec<1.0.0b5
spec.add_tag({'name': 'Pet', 'description': 'Operations on pets'})
spec.add_path('/pets/', operations=...)
spec.definition('Pet', properties=...)

# apispec>=1.0.0b5
spec.tag({'name': 'Pet', 'description': 'Operations on pets'})
spec.path('/pets/', operations=...)
spec.components.schema('Pet', properties=...)

• Plugins can define parameter_helper and response_helper to modify parameter and response components definitions.

• MarshmallowPlugin resolves schemas in parameters and responses components.

• Components helpers may return None as a no-op rather than an empty dict (336).

Bug fixes:

• MarshmallowPlugin.schema_helper does not crash when no schema is passed (336).

Deprecations/Removals:

• The legacy response_helper feature is removed. The same can be achieved from operation_helper.

• Backwards-incompatible: apispec.ext.flask, apispec.ext.bottle, and apispec.ext.tornado are moved to a separate package, apispec-webframeworks. (302).

If you use these plugins, install apispec-webframeworks and update your imports like so:

# apispec<1.0.0b4
from apispec.ext.flask import FlaskPlugin

# apispec>=1.0.0b4
from apispec_webframeworks.flask import FlaskPlugin

Thanks ergo for the suggestion and the PR.

Features:

• [apispec.core]: Backwards-incompatible: openapi_version parameter of APISpec class does not default to '2.0' anymore and info parameter is merged with **options kwargs.

Bug fixes:

• [apispec.ext.marshmallow]: Exclude load_only fields when documenting responses (119). Thanks luisincrespo for reporting.

• [apispec.ext.marshmallow]: Exclude dump_only fields when documenting request body parameter schema.

• Drop deprecated plugin interface. Only plugin classes are now supported. This includes the removal of APISpec's register_*_helper methods, as well as its schema_name_resolver parameter. Also drop deprecated apispec.utils.validate_swagger. (259)

• Use yaml.safe_load instead of yaml.load when reading docstrings (278). Thanks lbeaufort for the suggestion and the PR.

Features:

• [apispec.core]: Backwards-incompatible: Remove Path class. Plugins' path_helper methods should now return a path as a string and optionally mutate the operations dictionary (238).

• [apispec.core]: Backwards-incompatible: YAML support is optional. To install with YAML support, use pip install 'apispec[yaml]'. You will need to do this if you use FlaskPlugin, BottlePlugin, or TornadoPlugin (251).

• [apispec.ext.marshmallow]: Allow overriding the documentation for a field's default. This is especially useful for documenting callable defaults (196).

Features:

• [apispec.core]: Backwards-incompatible: Change plugin interface. Plugins are now child classes of apispec.BasePlugin. Built-in plugins are still usable with the deprecated legacy interface. However, the new class interface is mandatory to pass parameters to plugins or to access specific methods that used to be accessed as module level functions (typically in apispec.ext.marshmallow.swagger). Also, schema_name_resolver is now a parameter of apispec.ext.marshmallow.MarshmallowPlugin. It can still be passed to APISpec while using the legacy interface. (207)

• [apispec.core]: Backwards-incompatible: APISpec.openapi_version is now an apispec.utils.OpenAPIVersion instance.

Features:

• [apispec.core]: Backwards-incompatible: Rename apispec.utils.validate_swagger to apispec.utils.validate_spec and apispec.exceptions.SwaggerError to apispec.exceptions.OpenAPIError. Using validate_swagger will raise a DeprecationWarning (224).

• [apispec.core]: apispec.utils.validate_spec no longer relies on the check_api NPM module. prance and openapi-spec-validator are required for validation, and can be installed using pip install 'apispec[validation]' (224).

• [apispec.core]: Deep update components instead of overwriting components for OpenAPI 3 (222). Thanks Guoli-Lyu.

Bug fixes:

• [apispec.ext.marshmallow]: Fix description for parameters in OpenAPI 3 (223). Thanks again Guoli-Lyu.

Other changes:

• Drop official support for Python 3.4. Only Python 2.7 and >=3.5 are supported.

Features:

• [apispec.ext.marshmallow]: Fix OpenAPI 3 conversion of schemas in parameters (217). Thanks Guoli-Lyu for the PR.

Features:

• [apispec.ext.marshmallow]: Resolve an array of schema objects in parameters (209). Thanks cvlong for reporting and implementing this.

Features:

• [apispec.ext.marshmallow]: Document values parameter of Dict field as additionalProperties (201). Thanks UrKr.

Features:

• [apispec.ext.marshmallow]: Recurse over properties when resolving schemas (186). Thanks lphuberdeau.

• [apispec.ext.marshmallow]: Support writeOnly and nullable in OpenAPI 3 (fall back to x-nullable for OpenAPI 2) (165). Thanks lafrech.

Bug fixes:

• [apispec.ext.marshmallow]: Always use field.missing instead of field.default when introspecting fields (32). Thanks lafrech.

Other changes:

• [apispec.ext.marshmallow]: Refactor some of the internal functions in apispec.ext.marshmallow.swagger for consistent API (199). Thanks lafrech.

Features:

• [apispec.core]: Maintain order in which methods are added to an endpoint (189). Thanks lafrech.

Other changes:

• [apispec.core]: Path no longer inherits from dict (190). Thanks lafrech.

Features:

• [apispec.ext.marshmallow]: Respect data_key argument on fields (in marshmallow 3). Thanks lafrech.

Features:

• [apispec.ext.bottle]: Allow app to be passed to spec.add_path (188). Thanks dtaniwaki for the PR.

Bug fixes:

• [apispec.ext.marshmallow]: Fix issue where "body" and "required" were getting overwritten when passing a Schema to a parameter (168, 184). Thanks dlopuch and mathewmarcus for reporting and thanks mathewmarcus for the PR.

• [apispec.ext.marshmallow]: Use dump_to for name even if load_from does not match it (178). Thanks LeonAgmonNacht for reporting and thanks lafrech for the fix.

Features:

• [apispec.core]: Add Spec.to_yaml method for serializing to YAML (161). Thanks jd.

Features:

• [apispec.core and apispec.ext.marshmallow]: Add limited support for OpenAPI v3. Pass openapi_version='3.0.0' to Spec to use it (165). Thanks Bangertm.

Features:

• [apispec.core and apispec.ext.marshmallow]: Add schema_name_resolver param to APISpec for resolving ref names for marshmallow Schemas. This is useful when a self-referencing schema is nested within another schema (167). Thanks buxx for the PR.

Bug fixes:

• [apispec.ext.flask]: Don't document view methods that aren't included in app.add_url_rule(..., methods=[...])) (173). Thanks ukaratay.

Features:

• [apispec.core]: Add register_operation_helper.

Bug fixes:

• Order of plugins does not matter (136).

Thanks yoichi for these changes.

Features:

• [apispec.ext.marshmallow]: Generate "enum" property with single entry when the validate.Equal validator is used (155). Thanks Bangertm for the suggestion and PR.

Bug fixes:

• Allow OPTIONS to be documented (162). Thanks buxx for the PR.

• Fix regression from 0.25.3 that caused a KeyError (163). Thanks yoichi.

Bug fixes:

• [apispec.ext.marshmallow]: Fix swagger location mapping for default_in param in fields2parameters (156). Thanks decaz.

Bug fixes:

• [apispec.ext.marshmallow]: Correctly handle multiple fields with location=json (75). Thanks shaicantor for reporting and thanks yoichi for the patch.

Bug fixes:

• [apispec.ext.marshmallow]: Avoid AttributeError when passing non-dict items to path objects (151). Thanks yoichi.

Bug fixes:

• [apispec.ext.marshmallow]: Fix use_instances when many=True is set (148). Thanks theirix.

Features:

• [apispec.ext.marshmallow]: Add use_instances parameter to fields2paramters (144). Thanks theirix.

Other changes:

• Don't swallow YAMLError when YAML parsing fails (135). Thanks djanderson for the suggestion and the PR.

Features:

• [apispec.ext.marshmallow]: Add swagger.map_to_swagger_field decorator to support custom field classes (120). Thanks frol for the suggestion and thanks dradetsky for the PR.

Bug fixes:

• [apispec.ext.marshmallow]: Fix swagger location mapping for default_in param in property2parameter (142). Thanks decaz.

• Pass operations constructed by plugins to downstream marshmallow plugin (138). Thanks yoichi.

• [apispec.ext.marshmallow] Generate parameter specification from marshmallow Schemas (127). Thanks ewalker11 for the suggestion thanks yoichi for the PR.

• [apispec.ext.flask] Add support for Flask MethodViews (85, 125). Thanks lafrech and boosh for the suggestion. Thanks djanderson and yoichi for the PRs.

• Release wheel distribution.

Bug fixes:

• [apispec.ext.marshmallow]: Properly handle callable default values in output spec (131). Thanks NightBlues.

Bug fixes:

• [apispec.ext.marshmallow]: Include default in output spec when False is the default for a Boolean field (130). Thanks nebularazer.

Features:

• [apispec.ext.bottle] Added bottle plugin (128). Thanks lucasrc.

Features:

• [apispec.ext.marshmallow] Sort list of required field names in generated spec (124). Thanks dradetsky.

Bug fixes:

• [apispec.ext.tornado]: Fix compatibility with Tornado>=4.5.

• [apispec.ext.tornado]: Fix adding paths for handlers with coroutine methods in Python 2 (99).

Features:

• [apispec.core]: Definition helper functions receive the definition keyword argument, which is the current state of the definition (122). Thanks martinlatrille for the PR.

Other changes:

• [apispec.ext.marshmallow] Backwards-incompatible: Remove dump parameter from schema2parameters, fields2parameters, and field2parameter (114). Thanks lafrech and frol for the feedback and lafrech for the PR.

Features:

• [apispec.core]: Add extra_fields parameter to APISpec.definition (110). Thanks lafrech for the PR.

• [apispec.ext.marshmallow]: Preserve the order of choices (113). Thanks frol for the PR.

Bug fixes:

• [apispec.ext.marshmallow]: 'discriminator' is no longer valid as field metadata. It should be defined by passing extra_fields={'discriminator': '...'} to APISpec.definition. Thanks for reporting, lafrech.

• [apispec.ext.marshmallow]: Allow additional properties when translating Nested fields using allOf (108). Thanks lafrech for the suggestion and the PR.

• [apispec.ext.marshmallow]: Respect dump_only and load_only specified in class Meta (84). Thanks lafrech for the fix.

Other changes:

• Drop support for Python 3.3.

Features:

• [apispec.ext.marshmallow]: Translate allow_none on Fields to x-nullable (66). Thanks lafrech.

Bug fixes:

• [apispec.ext.marshmallow]: Fix corruption of Schema._declared_fields when serializing an APISpec (107). Thanks serebrov for the catch and patch.

Bug fixes:

• [apispec.ext.marshmallow]: Fix behavior when passing Schema instances to APISpec.definition. The Schema's class will correctly be registered as a an available ref (84). Thanks lafrech for reporting and for the PR.

Bug fixes:

• [apispec.ext.tornado]: Remove usage of inspect.getargspec for Python >= 3.3 (102). Thanks matijabesednik.

Bug fixes:

• [apispec.ext.marshmallow]: Prevent unnecessary warning when generating specs for marshmallow Schema's with autogenerated fields (95). Thanks khorolets reporting and for the PR.

• [apispec.ext.marshmallow]: Correctly translate Length validator to minItems and maxItems for array-type fields (Nested and List) (97). Thanks YuriHeupa for reporting and for the PR.

Features:

• [apispec.ext.marshmallow]: Add support for properties that start with x-. Thanks martinlatrille for the PR.

Features:

• [apispec.core]: Allow description to be passed to APISpec.definition (93). Thanks martinlatrille.

Features:

• [apispec.ext.marshmallow]: Allow 'query' to be passed as a field location (89). Thanks lafrech.

Bug fixes:

• [apispec.ext.flask]: Properly strip off basePath when APPLICATION_ROOT is set on a Flask app's config (78). Thanks deckar01 for reporting and asteinlein for the PR.

Features:

• [apispec.core]: Maintain order in which paths are added to a spec (87). Thanks ranjanashish for the PR.

• [apispec.ext.marshmallow]: Maintain order of fields when ordered=True on Schema. Thanks again ranjanashish.

Features:

• [apispec.ext.marshmallow]: Add support for Dict field (80). Thanks ericb for the PR.

• [apispec.ext.marshmallow]: dump_only fields add readOnly flag in OpenAPI spec (79). Thanks itajaja for the suggestion and PR.

Bug fixes:

• [apispec.ext.marshmallow]: Properly exclude nested dump-only fields from parameters (82). Thanks incognick for the catch and patch.

Support:

• Update tasks.py for compatibility with invoke>=0.13.0.

Features:

• [apispec.ext.marshmallow]: Inspect validators to set additional attributes (66). Thanks deckar01 for the PR.

Bug fixes:

• [apispec.ext.marshmallow]: Respect partial parameters on Schemas (74). Thanks incognick for reporting.

Bug fixes:

• [apispec.ext.flask]: Flask plugin respects APPLICATION_ROOT from app's config (69). Thanks deckar01 for the catch and patch.

• [apispec.ext.marshmallow]: Fix support for plural schema instances (71). Thanks again deckar01.

Features:

• Support vendor extensions on paths (65). Thanks lucascosta for the PR.

• Backwards-incompatible: Remove support for old versions (<=0.15.0) of webargs.

Bug fixes:

• Fix error message when plugin does not have a setup() function.

• [apispec.ext.marshmallow] Fix bug in introspecting self-referencing marshmallow fields, i.e. fields.Nested('self') (55). Thanks whoiswes for reporting.

• [apispec.ext.marshmallow] field2property no longer pops off location from a field's metadata (67).

Support:

• Lots of new docs, including a User Guide and improved extension docs.

Note: This version is a re-upload of 0.10.0. There is no 0.10.0 release on PyPI.

Features:

• Add Tornado extension (62).

Bug fixes:

• Compatibility fix with marshmallow>=2.7.0 (64).

• Fix bug that raised error for Swagger parameters that didn't include the in key (63).

Big thanks lucascosta for all these changes.

Bug fixes:

• Fix generation of metadata for Nested fields (61). Thanks martinlatrille.

Features:

• Add APISpec.add_tags method for adding Swagger tags. Thanks martinlatrille.

Bug fixes:

• Fix bug in marshmallow extension where metadata was being lost when converting marshmallow Schemas when many=False. Thanks again martinlatrille.

Other changes:

• Remove duplicate SWAGGER_VERSION from api.ext.marshmallow.swagger.

Support:

• Update docs to reflect rename of Swagger to OpenAPI.

Features:

• apispec.ext.marshmallow.swagger.schema2jsonschema properly introspects Schema instances when many=True (53). Thanks frol for the PR.

Bug fixes:

• Fix error reporting when an invalid object is passed to schema2jsonschema or schema2parameters (52). Thanks again frol.

Features:

• APISpec.add_path accepts Path objects (49). Thanks Trii for the suggestion and the implementation.

Bug fixes:

• Use correct field name in "required" array when load_from and dump_to are used (48). Thanks benbeadle for the catch and patch.

Features:

• Add APISpec#add_parameter for adding common Swagger parameter objects. Thanks jta.

• The field name in a spec will be adjusted if a Field's load_from and dump_to attributes are the same. 43. Thanks again jta.

Bug fixes:

• Fix bug that caused a stack overflow when adding nested Schemas to an APISpec (31, 41). Thanks alapshin and itajaja for reporting. Thanks itajaja for the patch.

• schema2jsonschema and schema2parameters can introspect a marshmallow Schema instance as well as a Schema class (37). Thanks frol.

• Backwards-incompatible: The first argument to schema2jsonschema and schema2parameters was changed from schema_cls to schema.

Bug fixes:

• Handle conflicting signatures for plugin helpers. Thanks AndrewPashkin for the catch and patch.