Merge pull request #42 from apiflask/sync-1.2.0

CHANGES.md

@@ -1,11 +1,45 @@
-## Versions 1.2.0
-
-- [1.2.0 milestone](https://github.com/apiflask/apiflask/milestone/12)
-- [1.2.0 kanban](https://github.com/apiflask/apiflask/projects/3)
+## Version 1.2.1
 
 Released: -
 
 
+## Version 1.2.0
+
+Released: 2023/1/8
+
+- **[Breaking change]** Add `apiflask.views.MethodView` to replace `flask.views.MethodView`, raise error if
+  using `flask.views.MethodView` ([issue #341][issue_341]).
+- **[Breaking change]** Change the status code of request validation error from 400 to 422 ([issue #345][issue_345]).
+- Add `Enum` field from marshmallow 3.18.
+- Fix OpenAPI spec generating for path parameters when path schema is provided ([issue #350][issue_350]).
+- Add `spec_plugins` param to `APIFlask` class to support using custom apispec plugins ([issue #349][issue_349]).
+- Improve the default bypassing rules to support bypass blueprint's static endpoint and
+  Flask-DebugToolbar ([issue #344][issue_344], [issue #369][issue_369]).
+- Explicitly check if `view_func.view_class` is `MethodViewType` in `add_url_rule` ([issue #379][issue_379]).
+- The schema fields are now in order by default, which ensures the output of `flask spec` is deterministic
+  ([issue #373][issue_373]).
+
+[issue_350]: https://github.com/apiflask/apiflask/issues/350
+[issue_349]: https://github.com/apiflask/apiflask/issues/349
+[issue_345]: https://github.com/apiflask/apiflask/issues/345
+[issue_344]: https://github.com/apiflask/apiflask/issues/344
+[issue_369]: https://github.com/apiflask/apiflask/issues/369
+[issue_379]: https://github.com/apiflask/apiflask/issues/379
+[issue_373]: https://github.com/apiflask/apiflask/issues/373
+[issue_341]: https://github.com/apiflask/apiflask/issues/341
+
+
+## Version 1.1.3
+
+Released: 2022/9/4
+
+- Fix some tests and import statements for Flask 2.2 ([pr #343][pr_343]).
+- Pin Flask < 2.2 as a temp fix for the breaking changes of class-based view support ([issue #341][issue_341]).
+
+[pr_343]: https://github.com/apiflask/apiflask/pull/343
+[issue_341]: https://github.com/apiflask/apiflask/issues/341
+
+
 ## Version 1.1.2
 
 Released: 2022/8/13

README.md

@@ -178,7 +178,7 @@ def update_pet(pet_id, data):
 from apiflask import APIFlask, Schema, abort
 from apiflask.fields import Integer, String
 from apiflask.validators import Length, OneOf
-from flask.views import MethodView
+from apiflask.views import MethodView
 
 app = APIFlask(__name__)
 
@@ -199,16 +199,13 @@ class PetOut(Schema):
     category = String()
 
 
-# “app.route”只是快捷方式，你也可以直接使用“app.add_url_rule”
-@app.route('/')
 class Hello(MethodView):
 
     # 使用 HTTP 方法名作为类方法名
     def get(self):
         return {'message': 'Hello!'}
 
 
-@app.route('/pets/<int:pet_id>')
 class Pet(MethodView):
 
     @app.output(PetOut)
@@ -227,6 +224,10 @@ class Pet(MethodView):
         for attr, value in data.items():
             pets[pet_id][attr] = value
         return pets[pet_id]
+
+
+app.add_url_rule('/', view_func=Hello.as_view('hello'))
+app.add_url_rule('/pets/<int:pet_id>', view_func=Pet.as_view('pet'))
 ```
 </details>
 
@@ -311,6 +312,7 @@ APIFlsak 是 Flask 之上的一层包装。你只需要记住下面几点区别
 
 - 当创建程序实例时，使用 `APIFlask` 而不是 `Flask`。
 - 当创建蓝本实例时，使用 `APIBlueprint` 而不是 `Blueprint`。
+- 当创建类视图时，使用 `apiflask.views.MethodView` 而不是 `flask.views.MethodView`。
 - APIFlask 提供的 `abort()` 函数（`apiflask.abort`）返回 JSON 错误响应。
 
 下面的 Flask 程序：
@@ -348,11 +350,11 @@ def hello():
 
 APIFlask 接受 marshmallow schema 作为数据 schema，它使用 webargs 验证请求数据是否符合 schema 定义，并且使用 apispec 生成 schema 对应的 OpenAPI 表示。
 
-你可以像以前那样构建 marshmallow schema。对于一些常用的 marshmallow 函数和类，你可以选择从 APIFlask 导入（你也可以直接从 marshmallow 导入）：
+你可以像以前那样构建 marshmallow schema。对于一些常用的 marshmallow 函数和类，你可以从 APIFlask 导入：
 
 - `apiflask.Schema`：schema 基类。
-- `apiflask.fields`：marshmallow 字段，包含来自 marshmallow、Flask-Marshmallow 和 webargs 的字段类。注意，别名字段（`Url`、`Str`、`Int`、`Bool` 等）已被移除（在 [marshmallow #1828](https://github.com/marshmallow-code/marshmallow/issues/1828) 投票移除这些别名字段）。
-- `apiflask.validators`：marshmallow 验证器（在 [marshmallow #1829](https://github.com/marshmallow-code/marshmallow/issues/1829) 投票为验证器相关的 API 使用更好的命名）。
+- `apiflask.fields`：marshmallow 字段，包含来自 marshmallow、Flask-Marshmallow 和 webargs 的字段类。注意，别名字段（`Url`、`Str`、`Int`、`Bool` 等）已被移除。
+- `apiflask.validators`：marshmallow 验证器投票为验证器相关的 API 使用更好的命名）。
 
 ```python
 from apiflask import Schema

docs/comparison.md

@@ -121,7 +121,7 @@ def create_pet():
 
 - Add an auto-summary for the view function based on the name of view functions.
 - Add success response (200) for a bare view function that only uses route decorators.
-- Add validation error response (400) for view functions that use `input` decorator.
+- Add validation error response (422) for view functions that use `input` decorator.
 - Add authentication error response (401) for view functions that use `auth_required` decorator.
 - Add 404 response for view functions that contain URL variables.
 - Add response schema for potential error responses of view function passed with `doc` decorator. For example, `doc(responses=[404, 405])`.

docs/configuration.md

@@ -711,7 +711,7 @@ app.config['NOT_FOUND_DESCRIPTION'] = 'Missing'
 The status code of validation error response.
 
 - Type: `int`
-- Default value: `400`
+- Default value: `422`
 - Examples:
 
 ```python

docs/error-handling.md

@@ -26,7 +26,7 @@ description. However, in APIFlask, these errors will be returned in JSON format
 the following preset fields:
 
 - `message`: The HTTP reason phrase or a custom error description.
-- `detail`: An empty dict (404/405/500) or the error details of the request validation (400).
+- `detail`: An empty dict (404/405/500) or the error details of the request validation (422).
 
 You can control this behavior with the `json_errors` parameter when creating the APIFlask
 instance, and it defaults to `True`:
@@ -231,7 +231,7 @@ The error object is an instance of [`HTTPError`][apiflask.exceptions.HTTPError],
 so you can get error information via its attributes:
 
 - status_code: If the error is triggered by a validation error, the value will be
-    400 (default) or the value you passed in config `VALIDATION_ERROR_STATUS_CODE`.
+    422 (default) or the value you passed in config `VALIDATION_ERROR_STATUS_CODE`.
     If the error is triggered by [`HTTPError`][apiflask.exceptions.HTTPError]
     or [`abort`][apiflask.exceptions.abort], it will be the status code
     you passed. Otherwise, it will be the status code set by Werkzueg when

docs/migrating.md

@@ -81,11 +81,10 @@ APIFlask support to use the `MethodView`-based view class, for example:
 
 ```python
 from apiflask import APIFlask, Schema, input, output
-from flask.views import MethodView
+from apiflask.views import MethodView
 
 # ...
 
-@app.route('/pets/<int:pet_id>', endpoint='pet')
 class Pet(MethodView):
 
     decorators = [doc(responses=[404])]
@@ -107,10 +106,9 @@ class Pet(MethodView):
     @app.output(PetOut)
     def patch(self, pet_id, data):
         pass
-```
 
-APIFlask supports to use the `route` decorator on a `MethodView`-based view class as a
-shortcut, but you can also use the `add_url_rule` method to register it for flexibility.
+app.add_url_rule('/pets/<int:pet_id>', view_func=Pet.as_view('pet'))
+```
 
 The `View`-based view class is not supported, you can still use it but currently
 APIFlask can't generate OpenAPI spec (and API documentation) for it.

docs/openapi.md

@@ -41,6 +41,22 @@ a spec process function to update the spec before it returns. See
 *[Register a spec processor](#register-a-spec-processor)* for more details.
 
 
+### Automation behaviors
+
+When generating the OpenAPI spec from your code, APIFlask has some automation behaviors:
+
+- Generate a default operation summary from the name of the view function.
+- Generate a default operation description from the docstring of the view function.
+- Generate tags from the name of blueprints.
+- Add a default 200 response for any views registered to the application.
+- Add a 422 response if the view is decorated with `app.input`.
+- Add a 401 response if the view is decorated with `app.auth_required`.
+- Add a 404 response if the view's URL rule contains variables.
+
+All these automation behaviors can be disabled with
+[the corresponding configurations](/configuration/#automation-behavior-control).
+
+
 ### The spec format
 
 The default format of the OpenAPI spec is JSON, while YAML is also supported.
@@ -431,7 +447,7 @@ def get_pet(pet_id):
 There are some automatic behaviors on operation `responses` object:
 
 - If the `input` decorator is added to the view function, APIFlask will add
-a `400` response.
+a `422` response.
 - When the `auth_required` decorator is added to the view function, APIFlask will
 add a `401` response.
 - If the view function only use the route decorator, APIFlask will add a default
@@ -740,7 +756,7 @@ def hello():
 ### Alternative operation `responses`
 
 As described above, APIFlask will add some responses based on the decorators you added
-on the view function (200, 400, 401, 404). Sometimes you may want to add alternative
+on the view function (200, 422, 401, 404). Sometimes you may want to add alternative
 responses the view function will return, then you can use the `@app.doc(responses=...)`
 parameter, it accepts the following values:
 

docs/request.md

@@ -10,7 +10,7 @@ Basic concepts on request handling:
 - Use one or more [`app.input()`](/api/app/#apiflask.scaffold.APIScaffold.input) to declare
   an input source, and use the `location` to declare the input location.
 - If the parsing and validating success, the data will pass to the view function.
-  Otherwise, a 400 error response will be returned automatically.
+  Otherwise, a 422 error response will be returned automatically.
 
 
 ## Request locations
@@ -80,7 +80,7 @@ def get_article(category, article_id, query, data):
 
     Notice the argument name for URL variables (`category, article_id`) must match the variable name.
 
-Otherwise, a 400 error response will be returned automatically. Like any other error response,
+Otherwise, a 422 error response will be returned automatically. Like any other error response,
 this error response will contain `message` and `detail` fields:
 
 - `message`
@@ -108,8 +108,8 @@ The value of `<location>` is where the validation error happened.
 
 - status code
 
-The default status code of validation error is 404, you can change this via the
-config `AUTH_ERROR_STATUS_CODE`.
+The default status code of validation error is 422, you can change this via the
+config `VALIDATION_ERROR_STATUS_CODE`.
 
 
 ## Dict schema

docs/schema.md

@@ -5,9 +5,8 @@ section first in the Basic Usage chapter for the basics of writing input and out
 
 Basic concepts on data schema:
 
-- APIFlask schema = [marshmallow](https://github.com/marshmallow-code/marshmallow) schema.
-- APIFlask's `apiflask.Schema` base class is directly imported from marshmallow, see the
-  [API documentation](https://marshmallow.readthedocs.io/en/stable/marshmallow.schema.html)
+- APIFlask's `apiflask.Schema` base class is directly imported from marshmallow with some minor changes,
+  see the [API documentation](https://marshmallow.readthedocs.io/en/stable/marshmallow.schema.html)
   for the details.
 - We recommend separating input and output schema. Since the output data is not
   validated, you don't need to define validators on output fields.