Changelog

0.17.0 (2019-09-19)

Features:

• Backwards-incompatible: Only return status code and short name in error handler (#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. (#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. (#81)
• Add content_type argument to Blueprint.arguments and provide reasonable default content type for form and files (#83).
• Add description parameter to Blueprint.arguments to pass description for requestBody (#93).
• Allow customization of docstring delimiter string (#49).
• Support file uploads as multipart/form-data (#97).

Bug fixes:

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

Other changes:

• Backwards-incompatible: Don’t republish NestedQueryArgsParser anymore. This belongs to user code and can be copied from webargs doc (#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 (#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. (#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 (#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. (#75)

0.15.1 (2019-06-18)

Bug fixes:

• marshmallow 3.0.0rc7 compatibility (#77).

0.15.0 (2019-05-09)

Features:

• Add parameters to pass examples and headers in Blueprint.response decorator (#63).
• Add parameters to pass examples for requestBody in OpenAPI v3 in Blueprint.arguments decorator (#68).
• Support status codes expressed as HTTPStatus in Blueprint.response decorator (#60). Thanks @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 (#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 (#45).
• Rename Api.definition as Api.schema. Keep Api.definition as an alias to Api.schema for backward compatibility (#53).

Bug fixes:

• Fix passing route with path parameter default value (#58). Thanks @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. (#52) Thanks @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 (#40).
• Allow view functions decorated with paginate to return a tuple with status and/or headers (#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) (#19). Thanks @fbergroth for reporting.
• Merge automatic path parameter documentation with existing manual doc rather than append as duplicate parameter (#23). Thanks @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. (#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 @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 @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 (#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 (#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 (#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 @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 (#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 (#8). Thanks @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.