Changelog
---------

0.18.2 (2019-10-21)
+++++++++++++++++++

Features:

- Official Python 3.8 support (:pr:`108`).

0.18.1 (2019-10-07)
+++++++++++++++++++

Bug fixes:

- Fix passing ``spec_kwargs`` in ``Api.__init__`` and ``app`` in
  ``Api.init_app`` (:issue:`103`).

0.18.0 (2019-09-22)
+++++++++++++++++++

Rename to `flask-smorest` (:issue:`42`).

0.17.0 (2019-09-19)
+++++++++++++++++++

Features:

- *Backwards-incompatible*: Only return status code and short name in error
  handler (:pr:`84`).
- *Backwards-incompatible*: Remove logging from error handler. Logging can be
  achieved in application code by overriding ``handle_http_exception``.
  Remove ``_prepare_error_response_content``. Reponse payload is computed in
  ``handle_http_exception``. (:pr:`85`)
- *Backwards-incompatible*: Remove ``InvalidLocationError``. The mapping from
  webargs locations to OAS locations is done in apispec and no exception is
  raised if an invalid location is passed. (:pr:`81`)
- Add ``content_type`` argument to ``Blueprint.arguments`` and provide
  reasonable default content type for ``form`` and ``files`` (:pr:`83`).
- Add ``description`` parameter to ``Blueprint.arguments`` to pass description
  for ``requestBody`` (:pr:`93`).
- Allow customization of docstring delimiter string (:issue:`49`).
- Support file uploads as `multipart/form-data` (:pr:`97`).

Bug fixes:

- Fix documentation of ``form`` and ``files`` arguments: use ``requestBody``
  in OAS3, document content type (:pr:`83`).

Other changes:

- *Backwards-incompatible*: Don't republish ``NestedQueryArgsParser`` anymore.
  This belongs to user code and can be copied from webargs doc (:pr:`94`).
- *Backwards-incompatible*: Bump minimum apispec version to 3.0.0.

0.16.1 (2019-07-15)
+++++++++++++++++++

Bug fixes:

- Fix detection of unhandled exceptions in error handler for Flask=>1.1.0
  (:pr:`82`).

Other changes:

- Bump minimum Flask version to 1.1.0. From this version on, uncaught
  exceptions are passed to the error handler as ``InternalServerError`` with
  the exception attached as ``original_exception`` attribute. (:pr:`82`)

0.16.0 (2019-06-20)
+++++++++++++++++++

Features:

- Add ``parameters`` argument to ``Blueprint.route`` to pass documentation for
  parameters that are shared by all operations of a path (:pr:`78`).

Other changes:

- *Backwards-incompatible*: Bump minimum apispec version to 2.0.0.
- *Backwards-incompatible*: Path parameters documentation passed in
  ``Blueprint.doc`` is no longer merged with automatic documentation. It should
  be passed in ``Blueprint.route`` instead.
- *Backwards-incompatible*: Remove ``Api.schema`` and ``Api.definition``.
  Those methods are useless since ``Schema`` components are automatically
  registered by apispec. Manual component registration is still possible using
  the internal apispec ``Components`` object. (:pr:`75`)

0.15.1 (2019-06-18)
+++++++++++++++++++

Bug fixes:

- marshmallow 3.0.0rc7 compatibility (:pr:`77`).

0.15.0 (2019-05-09)
+++++++++++++++++++

Features:

- Add parameters to pass examples and headers in ``Blueprint.response``
  decorator (:pr:`63`).
- Add parameters to pass examples for ``requestBody`` in OpenAPI v3 in
  ``Blueprint.arguments`` decorator (:pr:`68`).
- Support status codes expressed as ``HTTPStatus`` in ``Blueprint.response``
  decorator (:issue:`60`).
  Thanks :user:`Regzand` for reporting.

Other changes:

- Bump minimum apispec version to 1.3.2.
- Bump minimum werkzeug version to 0.15. With 0.14.x versions, `412` responses
  are returned with no content.
- *Backwards-incompatible*: When using ``Blueprint.doc`` decorator to provide
  additional documentation to the response described in the
  ``Blueprint.response`` decorator, the user must use the same format (``str``,
  ``int`` or ``HTTPStatus``) to express the status code in both decorators.
  This is a side-effect of (:issue:`60`). Now that headers and examples can
  be described in ``Blueprint.response``, this should not be a common use case.

0.14.1 (2019-04-18)
+++++++++++++++++++

Features:

- Official Python 3.7 support (:pr:`45`).
- Rename ``Api.definition`` as ``Api.schema``. Keep ``Api.definition`` as an
  alias to ``Api.schema`` for backward compatibility (:pr:`53`).

Bug fixes:

- Fix passing route with path parameter default value (:pr:`58`).
  Thanks :user:`zedrdave` for reporting.
- When no descrition is provided to ``Blueprint.response``, don't add an empty
  string as description in the docs.
- Fix returning a ``tuple`` subclass from a view function. Only raw ``tuple``
  instances are considered as Flask's (return value, status, headers).
  ``tuple`` subclasses are treated as ``list`` and can be paginated/dumped.
  Raw ``tuple`` return values should be cast to another type (e.g. ``list``)
  to be distinguished from (return value, status, headers) tuple. (:issue:`52`)
  Thanks :user:`asyncee` for reporting.

0.14.0 (2019-03-08)
+++++++++++++++++++

Features:

- Allow view functions decorated with ``response`` to return a ``Response``
  object or a tuple with status and/or headers (:pr:`40`).
- Allow view functions decorated with ``paginate`` to return a tuple with
  status and/or headers (:pr:`40`). The pagination header is now passed
  in the response tuple. Users relying on undocumented
  ``get_context()['headers']`` as a workaround to pass headers must update
  their code to pass headers in the response tuple as well.

Bug fixes:

- Fix ETag computation when headers contain a duplicate key.

0.13.1 (2019-02-13)
+++++++++++++++++++

Features:

- Register Werkzeug's ``UUIDConverter`` in ``Api`` so that ``uuid`` path
  parameters are correctly documented.

0.13.0 (2019-02-12)
+++++++++++++++++++

Features:

- Add ``flask_plugin`` and ``marshmallow_plugin`` spec kwargs to allow
  overriding base plugins.
- *Backwards-incompatible*: Rename ``plugins`` spec kwarg into
  ``extra_plugins``.
- *Backwards-incompatible*: Don't default to OpenAPI version 2.0. The version
  must now be specified, either as ``OPENAPI_VERSION`` app parameter or as
  ``openapi_version`` spec kwarg.
- Support apispec 1.0.0.
- *Backwards-incompatible*: Drop support for apispec 0.x.

0.12.0 (2018-12-02)
+++++++++++++++++++

Features:

- *Backwards-incompatible*: ``Api.register_converter`` doesn't register
  converter in Flask app anymore. It should be registered manually using
  ``app.url_map.converters['converter_name'] = Converter``.
- ``Api.definition``, ``Api.register_field`` and ``Api.register_converter`` can
  be called before app initialization. The information is buffered and passed
  to the internal ``APISpec`` object when it is created, in ``Api.init_app``.

0.11.2 (2018-11-28)
+++++++++++++++++++

Bug fixes:

- Fix typo in ``ErrorHandlerMixin._prepare_error_response_content``.

0.11.1 (2018-11-20)
+++++++++++++++++++

Features:

- The ``HTTP_METHODS`` list that defines the order of the methods in the spec
  is now a class attribute of ``Blueprint``. It can be overridden to enforce
  another order.

Bug fixes:

- Import ``Mapping`` from ``collections.abc`` rather than ``collections``. The
  latter is deprecated in Python 3.7 and will be removed in 3.8.
- Merge manual doc added with ``Blueprint.doc`` with automatic documentation
  after auto doc is prepared (i.e. adapted to OpenAPI version) (:issue:`19`).
  Thanks :user:`fbergroth` for reporting.
- Merge automatic path parameter documentation with existing manual doc rather
  than append as duplicate parameter (:issue:`23`).
  Thanks :user:`congenica-andrew` for reporting.
- Fix path parameter documentation structure when using OpenAPI v3.
- Document http status codes as strings, not integers.
- Fix use of Swagger UI config parameter ``OPENAPI_SWAGGER_UI_URL``.


Other changes:

- 100% test coverage !


0.11.0 (2018-11-09)
+++++++++++++++++++

Features:

- *Backwards-incompatible*: Rework of the ETag feature. It is now accesible
  using dedicated ``Blueprint.etag`` decorator. ``check_etag`` and ``set_etag``
  are methods of ``Blueprint`` and ``etag.INCLUDE_HEADERS`` is replaced with
  ``Blueprint.ETAG_INCLUDE_HEADERS``. It is enabled by default (only on views
  decorated with ``Blueprint.etag``) and disabled with ``ETAG_DISABLED``
  application configuration parameter. ``is_etag_enabled`` is now private.
  (:pr:`21`)
- *Backwards-incompatible*: The ``response`` decorator returns a ``Response``
  object rather than a (``Response`` object, status code) tuple. The status
  code is set in the ``Response`` object.
- Support apispec 1.0.0b5.

0.10.0 (2018-10-24)
+++++++++++++++++++

Features:

- *Backwards-incompatible*: Don't prefix all routes in the spec with
  ``APPLICATION_ROOT``. If using OpenAPI v2, set ``APPLICATION_ROOT`` as
  ``basePath``. If using OpenAPI v3, the user should specify ``servers``
  manually.
- *Backwards-incompatible*: In testing and debug modes, ``verify_check_etag``
  not only logs a warning but also raises ``CheckEtagNotCalledError`` if
  ``check_etag`` is not called in a resource that needs it.

0.9.2 (2018-10-16)
++++++++++++++++++

Features:

- ``Api.register_blueprint`` passes ``**options`` keyword parameters to
  ``app.register_blueprint`` to override ``Blueprint`` defaults. Thanks
  :user:`dryobates` for the suggestion.

0.9.1 (2018-10-11)
++++++++++++++++++

Features:

- Support apispec 1.0.0b3.

Bug fixes:

- Fix crash when serving documentation at root of application. Thanks
  :user:`fbergroth` for the suggestion.

0.9.0 (2018-10-01)
++++++++++++++++++

Features:

- *Backwards-incompatible*: When pagination parameters are out of range, the
  API does not return a `404` error anymore. It returns a `200` code with an
  empty list and pagination metadata (:pr:`10`).
- *Backwards-incompatible*: Remove dependency on python-dateutil. This is an
  optional marshmallow dependency. Whether it is needed to deserialize date,
  time, or datetime strings depends on the application.
- Rework internal features by using mixin classes. This makes the code cleaner
  and adds customization possibilities (:issue:`9`).
- *Backwards-incompatible*: ``DEFAULT_PAGINATION_PARAMETERS`` is a class
  attribute of ``Blueprint``.
- *Backwards-incompatible*: When no ``Page`` class is passed to ``pagination``,
  (i.e. when doing pagination in view function), the pagination parameters are
  passed as a ``PaginationParameters`` object. The item count must be passed by
  setting it as ``item_count`` attribute of the ``PaginationParameters``
  object. The ``set_item_count`` function is removed.
- The pagination header name can be configured by overriding
  ``PAGINATION_HEADER_FIELD_NAME`` class attribute of ``Blueprint``. If set to
  ``None``, no pagination header is added to the response.
- *Backwards-incompatible*: The ``paginate`` decorator doesn't use
  ``NestedQueryFlaskParser`` by default. It is renamed as
  ``NestedQueryArgsParser`` and it can be used by overriding
  ``Blueprint.ARGUMENTS_PARSER``.
- *Backwards-incompatible*: Drop Flask 0.x support. Flask>=1.0 is now required.
- Default error handler is registered for generic ``HTTPException``. Other
  extensions may register other handlers for specific exceptions or codes
  (:pr:`12`).

0.8.1 (2018-09-24)
++++++++++++++++++

Features:

- Add `page` (page number) to pagination metadata.
- Set `produces` and `consumes` root document attributes when using OpenAPI v2.

Bug fixes:

- Document body parameter correctly when using OpenAPI v3.

0.8.0 (2018-09-20)
++++++++++++++++++

Features:

- Add ``API_SPEC_OPTIONS`` app config parameter. Thanks :user:`xalioth` for the
  suggestion.
- *Backwards-incompatible*: ``Api`` accepts a ``spec_kargs`` parameter, passed
  as kwargs to the internal ``APISpec`` instance. ``spec_plugins`` is removed,
  plugins shall be passed as ``spec_kwargs={'plugins': [...]}``.
- *Backwards-incompatible*: Get `summary` and `description` from docstrings
  (:pr:`5`).
- Add support for marshmallow 3.0.0b13. 2.x and 3b are now supported.
- Add support for apispec 1.0.0b2. 0.x and 1b are now supported.

Bug fixes:

- Document response schema correctly when using OpenAPI 3 (:issue:`8`). Thanks
  :user:`ffarella` for reporting.

0.7.0 (2018-07-19)
++++++++++++++++++

Other changes:

- *Backwards-incompatible*: Remove ``_wrapper_class`` from ``Page``. Creating a
  custom pager is easier by just overriding ``Page`` methods.
- *Backwards-incompatible*: Let ``OPENAPI_SWAGGER_UI_SUPPORTED_SUBMIT_METHODS``
  default to "all methods" list.

0.6.1 (2018-06-29)
++++++++++++++++++

Bug fixes:

- Swagger UI integration: respect ``OPENAPI_SWAGGER_UI_URL`` configuration paramater.
- ``Api.register_field``: use ``APISpec.register_field`` rather than access ``self.spec.ma_plugin`` directly.

0.6.0 (2018-06-29)
++++++++++++++++++

Features:

- *Backwards-incompatible*: Use apispec 0.39.0 plugin class interface.
- *Backwards-incompatible*: Expose APISpec's ``register_field`` and ``register_converter methods`` from ``Api`` object. ``Api.register_converter`` signature is modified to make ``name`` parameter optional.
- Pass extra apispec plugins to internal APISpec instance.
- *Backwards-incompatible*: Drop official support for Python 3.4.

0.5.2 (2018-06-21)
++++++++++++++++++

Features:

- Pass OpenAPI version as ``OPENAPI_VERSION`` app config parameter.
- Add Swagger UI (3.x) integration.

0.5.1 (2018-06-18)
++++++++++++++++++

Features:

- ReDoc: Use unpkg CDN for 2.x version.

0.5.0 (2018-06-05)
++++++++++++++++++

Features:

- *Backwards-incompatible*: In ``Blueprint.route``, the endpoint name defaults to the function name with the case unchanged. Before this change, the name was lowercased.
- *Backwards-incompatible*: Pagination is now managed by dedicated ``Blueprint.paginate`` decorator.
- Add ``etag.INCLUDE_HEADERS`` to specify which headers to use for ETag computation (defaults to ``['X-Pagination']``).
- In ``verify_check_etag``, endpoint name is added to the warning message.

0.4.2 (2018-04-27)
++++++++++++++++++

Bug fixes:

- Pagination: don't crash if ``item_count`` is not set, just log a warning and set no pagination header.
- API spec: Fix leading/trailing slash issues in api-docs Blueprint. Fixes compatibility with Flask 1.0.

0.4.1 (2018-04-17)
++++++++++++++++++

Features:

- Allow multiple calls to ``Blueprint.arguments`` on a view function.
- Enforce order of fields in ``PaginationParametersSchema`` and ``PaginationMetadataSchema``.
- Minor improvements in test_examples.py.

0.4.0 (2018-04-05)
++++++++++++++++++

Features:

- *Backwards-incompatible*: The case of a parameter both in URL and in arguments Schema is now unsupported.
- *Backwards-incompatible*: By default, Schema parameter passed in ``Blueprint.arguments`` is documented as `required`.
- *Backwards-incompatible*: ``APISpec.register_field`` now uses apispec API. It must be passed a  ``(type, format)`` couple or an already registered ``Field`` class (this includes base marshmallow ``Fields``. When using ``(type, format)``, ``format`` doesn't default to ``None`` anymore.
- Preserve order when serving the spec file:
  - Fields are printed in declaration order if Schema.Meta.ordered is True
  - Methods in a method view are printed in this order: ['OPTIONS', 'HEAD', 'GET', 'POST', 'PUT', 'PATCH', 'DELETE']
  - Paths are added in declaration order

Bug fixes:

- Document response as array when using paginate_with.

0.3.0 (2018-03-02)
++++++++++++++++++

Features:

- Add leading and trailing ``/`` to OPENAPI_URL_PREFIX if missing.
- *Backwards-incompatible*: Change default URL path for OpenAPI JSON to ``'openapi.json'``.

Bug fixes:

- Fix OpenAPI docs URL paths.
- *Backwards-incompatible*: ``Blueprint.route(self, rule, **options)`` matches ``flask``'s ``Blueprint`` signature.

0.2.0 (2018-03-02)
++++++++++++++++++

Features:

- ``format`` parameter in ``register_converter`` and ``register_field`` is now optional and defaults to ``None``.
- APISpec inherits from original apispec.APISpec.
- *Backwards-incompatible*: The internal ``APISpec`` instance is now exposed as public attribute ``spec`` of ``Api``. ``register_converter`` and ``register_field`` are not proxied anymore by ``Api`` and must be called on ``spec``.
- *Backwards-incompatible*: ``Api.register_converter`` takes a ``name`` parameter and registers a converter in the ``Flask`` application as well as in its internal ``APISpec`` instance.
- *Backwards-incompatible*: ``Api.register_spec_plugin`` is removed. ``api.register_spec_plugin(...)`` shall be replaced with ``api.spec.setup_plugin(...)``.

0.1.1 (2018-02-16)
++++++++++++++++++

Bug fixes:

- Fix version number.

Support:

- Add dev-requirements.txt.

0.1.0 (2018-02-16)
++++++++++++++++++

First release.
