Changelog¶
Upgrade to the latest version:
$ pip3 install -U apiflask
> pip install -U apiflask
or check the currently installed version first:
$ pip3 show apiflask
> pip show apiflask
Version 2.3.1¶
Released: 2024/12/7
- Include input documentation in API spec when specifying
validation=False
on@input
decorator (issue #626).
Version 2.3.0¶
Released: 2024/11/25
- Support skipping the validation for the request body with
@input(validation=False)
(issue #573). - Enable CI test for Python 3.13.
Version 2.2.1¶
Released: 2024/9/8
- Fix OpenAPI spec for multiple content types with
json_or_form
location (issue #600).
Version 2.2.0¶
Released: 2024/8/3
- Fix deprecated warnings in tests (issue #594).
- Use postponed evaluation of annotations (pr #585).
- Add static OpenAPI docs example (issue #587).
- Add spec extensions support with
@doc(extensions=...)
for the view function (issue #571).
Version 2.1.3¶
Released: 2024/7/14
- Fix the
flask spec
command for latest Flask (issue #582).
Version 2.1.2¶
Released: 2024/7/6
- Deprecate the
__version__
attribute. Use feature detection orimportlib.metadata.version("apiflask")
instead. - Explicitly skip the data serialization for response with
app.output(FileSchema)
.
Version 2.1.1¶
Released: 2024/3/10
- Reuse the
File
,Config
field, and file-related validators from flask-marshmallow (issue #540). - Add support for a
--quiet
option to theflask spec
command (issue #548). - Fix the
flask spec
command for validators operating on complex data types (issue #547).
Version 2.1.0¶
Released: 2023/12/16
- Add
FileType
andFileSize
validators (issue #253). - Allow adding multiple media types for a response (issue #494).
- Support adding headers to the response schema (issue #507).
- Add support for adding decorators to the OpenAPI spec and documentation UI endpoints (issue #483).
- Fix the base repsonse schema inconsistency issue.
Version 2.0.2¶
Released: 2023/9/24
- Loose Flask version requirement to >= 2.0.0 and add test for minimum dependency versions (issue #478).
- Add file uploading example application (pr #476).
- Fix token authentication example application (pr #472).
Version 2.0.1¶
Released: 2023/8/15
- Add
Config
field to dump Flaskapp.config
variables (issue #468). - Fix the typing of newly updated
doc(responses)
parameter (issue #466).
Version 2.0.0¶
Released: 2023/7/26
Codename: Gongqing
Please see the migration guide for APIFlask 1.x -> 2.0.0.
- Drop Python 3.7 support.
- Drop Flask 1.x support (issue #442).
- Only pass keyword arguments to the view function. The argument name
of the parsed data from
app.input()
will be{location}_data
or the value ofarg_name
(issue #427). - Add
FileSchema
to generate OpenAPI file response (issue #447). - Support using
{}
to represent not only empty body (204) but also empty schema. Use{}
orEmptySchema
will not set the status code to 204 anymore. - Remove the previously deprecated code:
- The
tag
parameter in@app.doc
. - The
role
parameter in@app.auth_required
. - The
redoc_path
parameter inapiflask.APIFlask
and the/redoc
path.
- The
- Support setting a complete response OpenAPI spec throught the
app.doc(responses)
parameter (i.e.responses={400: {'description': '', 'content': ...}}
) (issue #327).
Version 1.3.1¶
Released: 2023/3/27
- Fix the import error when calling
apispec.yaml_utils.dict_to_yaml
(issue #419).
Version 1.3.0¶
Released: 2023/3/18
- Add
scurity_scheme_name
forHTTPBasicAuth
andHTTPTokenAuth
to define custom OpenAPI security scheme name (issue #410). - Add config
SPEC_PROCESSOR_PASS_OBJECT
to control the argument type of spec processor. Thespec
argument will be anapispec.APISpec
object when this config isTrue
(issue #213). - Add
content_type
parameter to theoutput()
decorator to customize the response's content/media type.
Version 1.2.3¶
Released: 2023/2/21
- Bypass OpenAPI spec generation for view methods (issue #406).
Version 1.2.2¶
Released: 2023/2/18
- Remove the validation of input locations (issue #259).
- Support passing
Function
type config toSWAGGER_UI_CONFIG
(issue #381). - Fix the base response support so that a custom class can be returned from the view function (issue #384).
Version 1.2.1¶
Released: 2023/1/15
- Support to generate the OpenAPI
servers
field when the reqeust context is available. Add the configAUTO_SERVERS
to control this automation behavior (issue #377).
Version 1.2.0¶
Released: 2023/1/8
- [Breaking change] Add
apiflask.views.MethodView
to replaceflask.views.MethodView
, raise error if usingflask.views.MethodView
(issue #341). - [Breaking change] Change the status code of request validation error from 400 to 422 (issue #345).
- Add
Enum
field from marshmallow 3.18. - Fix OpenAPI spec generating for path parameters when path schema is provided (issue #350).
- Add
spec_plugins
param toAPIFlask
class to support using custom apispec plugins (issue #349). - Improve the default bypassing rules to support bypass blueprint's static endpoint and Flask-DebugToolbar (issue #344, issue #369).
- Explicitly check if
view_func.view_class
isMethodViewType
inadd_url_rule
(issue #379). - The schema fields are now in order by default, which ensures the output of
flask spec
is deterministic (issue #373).
Version 1.1.3¶
Released: 2022/9/4
- Fix some tests and import statements for Flask 2.2 (pr #343).
- Pin Flask < 2.2 as a temp fix for the breaking changes of class-based view support (issue #341).
Version 1.1.2¶
Released: 2022/8/13
- Set default Elements router to
hash
to fix incorrect path updates.
Version 1.1.1¶
Released: 2022/8/3
- Improve CI setup and test again Python 3.10 and 3.11.
- Fix the typing of
APIFlask
path parameters (issue #329). - Update
MethodViewType
usages for Flask 2.2 (issue #335).
Version 1.1.0¶
Released: 2022/7/3
- Add a versioned docs for 1.x releases (https://v1.apiflask.com).
- Allow the view function to return a list as JSON response (issue #321).
- Add new docs UI support: RapiDoc, RapiPDF, and Elements (pr #308).
- Add a
docs_ui
parameter to APIFlask to set the API docs UI (can beswagger-ui
(default),redoc
,rapidoc
, andrapipdf
). - Deprecate the separate docs path
/redoc
and theredoc_path
parameter. - Add the following configuration variables for new docs support:
ELEMENTS_JS
ELEMENTS_CSS
ELEMENTS_LAYOUT
ELEMENTS_CONFIG
RAPIDOC_JS
RAPIDOC_THEME
RAPIDOC_CONFIG
RAPIPDF_JS
RAPIPDF_CONFIG
- Fix CLI entry point setup to prevent overwriting
flask
(issue #312)
Version 1.0.2¶
Released: 2022/5/21
- Combine custom security schemes (app.security_schemes) with existing values (issue #293).
- Add the missing
path
(view_args
) to the valid requestlocation
list (issue #301) - Fix the security scheme values to lowercase.
Version 1.0.1¶
Released: 2022/5/17
- Fix the async support for
app.auth_required
,app.input
, andapp.doc
decorators (issue #288). Thanks @jiashuChen!
Version 1.0.0¶
Released: 2022/5/4
Codename: Wujiaochang
- Remove the deprecated standalone decorators:
input
,output
,doc
, andauth_required
. Use app/blueprint decorators instead (e.g.input()
->app.input()
/bp.input()
). - Deprecate the following parameters (issue #237):
role
inapp.auth_required()
/bp.auth_required()
, useroles
and always pass a list.tag
inapp.doc()
/bp.doc()
, usetags
and always pass a list.
- Add a base class (
apiflask.scaffold.APIScaffold
) for common logic ofAPIFlask
andAPIBlueprint
, move route decorators and API-related decorators to this base class to improve the IDE auto-completion (issue #231). - Support customizing OpenAPI securitySchemes and operation security, this makes it possible to use any external authentication libraries (pull #232).
- Improve the way to detect blueprint from view endpoint to support the endpoints that contain dots (issue #211).
- Support file uploading (issue #123):
- Fix the content type of
form
andfiles
input locations. - Raise error if the user uses multiple body input locations ("files", "form", "json").
- Add
Form
field andform_and_files
location for better form upload support. - Rewrite the
files
to act likeform_and_files
, so that failed parsed file will be included in the returned data.
- Fix the content type of
- Allow to use
json_or_form
location and fields (DelimitedList
andDelimitedTuple
) from webargs (issue #254). - When creating a custom error processor, call it for generic HTTP errors even if the
json_errors
is set toFalse
when creating the app instance (issue #171).
Version 0.12.0¶
Released: 2022/3/2
- Move standalone decorators (input, output, auth_required, doc) to APIFlask/APIBlueprint classes. The old decorators are deprecated and will be removed in 1.0. (issue #187).
Version 0.11.0¶
Released: 2021/12/6
- Support creating custom error classes based on
HTTPError
. The position argumentstatus_code
ofHTTPError
is changed to a keyword argument, defaults to500
(issue #172).
Version 0.10.1¶
Released: 2021/11/26
- Fix missing headers for JSON error responses when catching Werkzeug exceptions (issue #173).
Version 0.10.0¶
Released: 2021/9/19
- Support using
add_url_rule
method on view classes (issue #110). - Revoke the undocumented name changes on
validates
andvalidates_schema
from marshmallow (issue #62). - Only expose marshmallow
fields
,validators
, andSchema
in APIFlask. - Remove the
status_code
field from the default error response (issue #124). - Add parameter
extra_data
toabort
andHTTPError
, it accepts a dict that will be added to the error response (issue #125). - Support passing
operation_id
in thedoc
decorator. The auo-generating of operationId can be enabled with configAUTO_OPERATION_ID
, defaults toFalse
(pull #131). - Support setting response links via
@output(links=...)
(issue #138).
Version 0.9.0¶
Released: 2021/8/10
- Support base response schema customization, add config
BASE_RESPONSE_SCHEMA
andBASE_RESPONSE_DATA_KEY
(issue #65). - Support setting custom schema name resolver via the
APIFlask.schema_name_resolver
attribute (issue #105). - Improve error handling (issue #107):
- Authentication error now calls app error processor function when
APIFlask(json_errors=True)
. The default HTTP reason phrase is used for auth errors. - Always pass an
HTTPError
instance to error processors. When you set a custom error processor, now you need to accept anHTTPError
instance as the argument. Thedetail
andheaders
attribute of the instance will be empty dict if not set. - Add an
error_processor
decorator forHTTPTokenAuth
andHTTPBasicAuth
, it can be used to register a custom error processor for auth errors.
- Authentication error now calls app error processor function when
- Support to config Redoc via the configuration variable
REDOC_CONFIG
(issue #121).
Version 0.8.0¶
Released: 2021/7/7
- Automatically add a 404 response in OpenAPI spec for routes contains URL variables (issue #78).
- Rename the private method
app.get_spec
toapp._get_spec
, add new parameterforce_update
. Theapp.spec
property now will always return the latest spec instead of the cached one (issue #79). - Support using
doc(responses={<STATUS_CODE>: <DESCRIPTION>})
to overwrite existing response descriptions. - Add configration variable
INFO
(andapp.info
attribute), it can be used to set the following info fields:description
,termsOfService
,contact
,license
(issue #98). - Rename the following configuration variables (issue #99):
AUTO_PATH_SUMMARY
->AUTO_OPERATION_SUMMARY
AUTO_PATH_DESCRIPTION
->AUTO_OPERATION_DESCRIPTION
Version 0.7.0¶
Released: 2021/6/24
- Support using async error processor and async spec processor (pull #57).
- Fix auto-tag support for nesting blueprint (pull #58).
- Support set the URL prefix of the OpenAPI blueprint with the
openapi_blueprint_url_prefix
argument (pull #64). - Add a
flask spec
command to output the OpenAPI spec to stdout or a file, also add new configLOCAL_SPEC_PATH
andLOCAL_SPEC_JSON_INDENT
(issue #61). - Re-add the
SPEC_FORMAT
config. Remove the auto-detection of the format fromAPIFlask(spec_path=...)
, now you have to set the format explicitly with theSPEC_FORMAT
config (issue #67). - Support to sync the local OpenAPI spec automatically. Add new config
SYNC_LOCAL_SPEC
(issue #68). - Change the default value of config
DOCS_FAVICON
to'https://apiflask.com/_assets/favicon.png'
, set toNone
to disable the favicon. - OpenAPI UI templates are move to
ui_templates.py
. - Revert the renames on pre/post decorators from marshmallow (issue #62).
- Change the default branch to "main".
- Move the source to the "src" directory.
- Enable pre-commit.
Version 0.6.3¶
Released: 2021/5/17
- Improve static request dispatch (pull #54).
Version 0.6.2¶
Released: 2021/5/16
- Fix static request dispatch for Flask 2.0 (issue #52).
Version 0.6.1¶
Released: 2021/5/15
- Fix type annotaion for Flask 2.0 (pull #48).
- Fix type annotaion for
schema
parameter ofinput
andoutput
(pull #49). - Fix type annotaion for imports by exporting top-level name explicitly (pull #49).
- Fix async for
dispatch_request
for Flask 2.0 (pull #50).
Version 0.6.0¶
Released: 2021/5/11
- Support using the
output
decorator on async views (pull #41). - Add
PaginationSchema
andpagination_builder
as basic pagination support (pull #42). - Import and rename the decorators from marshmallow (pull #43).
- Rename
utils
module tohelpers
(pull #44). - Add
default
parameter forget_reason_phrase
(pull #45).
Version 0.5.2¶
Released: 2021/4/29
- Allow returning a
Response
object in a view function decorated with theoutput
decorator. In this case, APIFlask will do nothing but return it directly (pull #38). - Skip Flask's
Blueprint
object when generating the OpenAPI spec (pull #37).
Version 0.5.1¶
Released: 2021/4/28
- Change the default endpoint of the view class to the original class name (pull #36).
- Allow passing the
methods
argument for theroute
decorator on view classes.
Version 0.5.0¶
Released: 2021/4/27
- Remove the support to generate
info.description
and tag description from module docstring, and also remove theAUTO_DESCRIPTION
config (pull #30). - Remove the configuration variable
DOCS_HIDE_BLUEPRINTS
, addAPIBlueprint.enable_openapi
as a replacement. - Support class-based views, now the
route
decorator can be used onMethodView
class. Other decorators (i.e.,@input
,@output
, etc.) can be used on view methods (i.e.,get()
,post()
, etc.) (pull #32). - No longer support to mix the use of
flask.Bluerpint
andapiflask.APIBluerpint
. - Support to use the
auth_required
decorator on app-widebefore_request
functions (pull #34).
Version 0.4.0¶
Released: 2021/4/20
- Merge the following configuration variables to
SUCCESS_DESCRIPTION
(pull #7):DEFAULT_2XX_DESCRIPTION
DEFAULT_200_DESCRIPTION
DEFAULT_201_DESCRIPTION
DEFAULT_204_DESCRIPTION
- Remove the following configuration variables (pull #7):
AUTO_HTTP_ERROR_RESPONSE
AUTH_ERROR_SCHEMA
- Add new configuration variables
YAML_SPEC_MIMETYPE
andJSON_SPEC_MIMETYPE
to support to customize the MIME type of spec response (pull #3). - Remove configuration variable
SPEC_TYPE
. - Fix the support to pass an empty dict as schema for 204 response (pull #12).
- Support set multiple examples for request/response body with
@output(examples=...)
and@iniput(examples=...)
(pull #23). - Add
auth_required(roles=...)
anddoc(tags=...)
parameters for list value,role
andtag
parameter now only accept string value (pull #26). - Add new configuration variable
OPENAPI_VERSION
to set the version of OAS (pull #27). - Rename
abort_json()
toabort()
(pull #29).
Version 0.3.0¶
Released: 2021/3/31
- First public version.
- Add type annotations and enable type check in tox (commit).
- Refactor the APIs (commit):
- Change base class
scaffold.Scaffold
to class decoratorutils.route_shortcuts
. - Merge the
_OpenAPIMixin
class intoAPIFlask
class. - Turn
security._AuthErrorMixin
intohandle_auth_error
function. - Add explicit parameter
role
andoptional
for@auth_required
decorator. - Rename module
errors
toexceptions
. - Rename
api_abort()
toabort_json()
. - Rename
get_error_message()
toget_reason_phrase()
and move it toutils
module. - Update the default value of config
AUTH_ERROR_DESCRIPTION
. - Add
validators
module. - Change
@doc(tags)
to@doc(tag)
.
- Change base class
- Support to pass a dict schema in
@output
decorator (commit). - Support to pass a dict schema in
@input
decorator (commit). - Check if the status code is valid for
abort_json
andHTTPError
(commit). - Add basic docstrings to generate the API reference documentation (commit).
- Support to set custom example for request/response body (commit).
Version 0.2.0¶
Released: 2021-3-27
- Fix various bugs.
- Refactor the package and tests (100% coverage).
- Rename most of the APIs.
- Add new APIs:
APIFlask
APIBlueprint
HTTPError
api_json
HTTPTokenAuth
HTTPBasicAuth
@doc
EmptySchema
- Add a bunch of new configuration variables:
DESCRIPTION
TAGS
CONTACT
LICENSE
SERVERS
EXTERNAL_DOCS
TERMS_OF_SERVICE
SPEC_FORMAT
AUTO_TAGS
AUTO_DESCRIPTION
AUTO_OPERATION_SUMMARY
AUTO_PATH_DESCRIPTION
AUTO_200_RESPONSE
DEFAULT_2XX_DESCRIPTION
DEFAULT_200_DESCRIPTION
DEFAULT_201_DESCRIPTION
DEFAULT_204_DESCRIPTION
AUTO_VALIDATION_ERROR_RESPONSE
VALIDATION_ERROR_STATUS_CODE
VALIDATION_ERROR_DESCRIPTION
VALIDATION_ERROR_SCHEMA
AUTO_AUTH_ERROR_RESPONSE
AUTH_ERROR_STATUS_CODE
AUTH_ERROR_DESCRIPTION
AUTH_ERROR_SCHEMA
AUTO_HTTP_ERROR_RESPONSE
HTTP_ERROR_SCHEMA
DOCS_HIDE_BLUEPRINTS
DOCS_FAVICON
REDOC_USE_GOOGLE_FONT
REDOC_STANDALONE_JS
SWAGGER_UI_CSS
SWAGGER_UI_BUNDLE_JS
SWAGGER_UI_STANDALONE_PRESET_JS
SWAGGER_UI_LAYOUT
SWAGGER_UI_CONFIG
SWAGGER_UI_OAUTH_CONFIG
- Support to hide blueprint from API docs with config
DOCS_HIDE_BLUEPRINTS
(commit) - Support to deprecate and hide an endpoint with
doc(hide=True, deprecated=True)
(commit) - Support to customize the API docs with various configuration variables. (commit)
- Support to set all fields of OpenAPI object and Info object (commit)
- Support YAML format spec (commit)
- Automatically register a validation error response for endpoints which use
@input
. (commit) - Automatically register a authorization error response for endpoints which use
@auth_required
. (commit) - Automatically add response schema for responses added with
@doc(responses=...)
. (commit) - Pass view arguments to view function as positional arguments (commit)
- Require Python 3.7 to use ordered dict (commit)
- Add shortcuts for
app.route
:app.get()
,app.post()
, etc. (commit) - Not an extension any more (commit)
Version 0.1.0¶
Released: 2021-1-27
- Add view functions without response schema into spec (commit)
- Set default response descriptions (commit)
- Stop relying on Flask-Marshmallow (commit)
- Change default spec path to
openapi.json
(commit) - Add support for enabling Swagger UI and Redoc at the same time (commit)
- Change default spec title and version (commit)
- Support auto generating summary from function name (commit)
- Start as a fork of APIFairy 0.6.2 at 2021-01-13.