Apispec

++++++++++++++++++++

Features:

- *Backwards-incompatible*: `basePath` is not removed from paths anymore.
Paths passed to ``APISpec.path`` should not contain the application base path
(:pr:`345`).
- Add ``apispec.ext.marshmallow.openapi.OpenAPIConverter.resolve_schema_class`` (:pr:`346`).
Thanks :user:`buxx`.

++++++++++++++++++++

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`
(:pr:`336`).

Bug fixes:

- ``MarshmallowPlugin.schema_helper`` does not crash when no schema is passed
(:pr:`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 <https://github.com/marshmallow-code/apispec-webframeworks>`_.
(:issue:`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 :user:`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 (:issue:`119`). Thanks :user:`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``. (:pr:`259`)
- Use ``yaml.safe_load`` instead of ``yaml.load`` when reading
docstrings (:issue:`278`). Thanks :user:`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 (:pr:`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`` (:pr:`251`).
- [apispec.ext.marshmallow]: Allow overriding the documentation for
a field's default. This is especially useful for documenting
callable defaults (:issue:`196`).