Sync changes for 1.1.2 version (#37)

Co-authored-by: Grey Li <[email protected]> Co-authored-by: Benno Rice <[email protected]> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> Co-authored-by: Andy Zhou <[email protected]>
apiflask · Aug 21, 2022 · b1b3447 · b1b3447
1 parent 6543cbf
commit b1b3447
Show file tree

Hide file tree

Showing 50 changed files with 480 additions and 409 deletions.
diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml
@@ -1,11 +1,19 @@
-name: build
+name: Tests
 on:
   push:
     branches:
       - main
+      - 'v*'
+    paths-ignore:
+      - 'docs/**'
+      - '*.md'
   pull_request:
     branches:
       - main
+      - 'v*'
+    paths-ignore:
+      - 'docs/**'
+      - '*.md'
 jobs:
   lint:
     name: lint

diff --git a/CHANGES.md b/CHANGES.md
@@ -6,6 +6,25 @@
 Released: -
 
 
+## 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][issue_329]).
+- Update `MethodViewType` usages for Flask 2.2 ([issue #335][issue_335]).
+
+[issue_329]: https://github.com/apiflask/apiflask/issues/329
+[issue_335]: https://github.com/apiflask/apiflask/issues/335
+
+
 ## Version 1.1.0
 
 Released: 2022/7/3

diff --git a/README.md b/README.md
@@ -127,12 +127,12 @@ pets = [
 ]
 
 
-class PetInSchema(Schema):
+class PetIn(Schema):
     name = String(required=True, validate=Length(0, 10))
     category = String(required=True, validate=OneOf(['dog', 'cat']))
 
 
-class PetOutSchema(Schema):
+class PetOut(Schema):
     id = Integer()
     name = String()
     category = String()
@@ -145,7 +145,7 @@ def say_hello():
 
 
 @app.get('/pets/<int:pet_id>')
-@app.output(PetOutSchema)
+@app.output(PetOut)
 def get_pet(pet_id):
     if pet_id > len(pets) - 1:
         abort(404)
@@ -155,8 +155,8 @@ def get_pet(pet_id):
 
 
 @app.patch('/pets/<int:pet_id>')
-@app.input(PetInSchema(partial=True))
-@app.output(PetOutSchema)
+@app.input(PetIn(partial=True))
+@app.output(PetOut)
 def update_pet(pet_id, data):
     # 验证且解析后的请求输入数据会
     # 作为一个字典传递给视图函数
@@ -188,12 +188,12 @@ pets = [
 ]
 
 
-class PetInSchema(Schema):
+class PetIn(Schema):
     name = String(required=True, validate=Length(0, 10))
     category = String(required=True, validate=OneOf(['dog', 'cat']))
 
 
-class PetOutSchema(Schema):
+class PetOut(Schema):
     id = Integer()
     name = String()
     category = String()
@@ -211,15 +211,15 @@ class Hello(MethodView):
 @app.route('/pets/<int:pet_id>')
 class Pet(MethodView):
 
-    @app.output(PetOutSchema)
+    @app.output(PetOut)
     def get(self, pet_id):
         """Get a pet"""
         if pet_id > len(pets) - 1:
             abort(404)
         return pets[pet_id]
 
-    @app.input(PetInSchema(partial=True))
-    @app.output(PetOutSchema)
+    @app.input(PetIn(partial=True))
+    @app.output(PetOut)
     def patch(self, pet_id, data):
         """Update a pet"""
         if pet_id > len(pets) - 1:

diff --git a/codecov.yml b/codecov.yml
@@ -0,0 +1 @@
+comment: false
diff --git a/docs/api-docs.md b/docs/api-docs.md
@@ -1,4 +1,4 @@
-# API documentations
+# API documentation
 
 APIFlask provides support to the following API documentation UIs:
 
@@ -64,7 +64,7 @@ Now the paths to docs and spec will be <http://localhost:5000/openapi/docs>
 and <http://localhost:5000/openapi/openapi.json>.
 
 
-## Add custom API documentations
+## Add custom API documentation
 
 You can easily add support to other API docs or serve the supported docs UI by yourself.
 
@@ -129,9 +129,9 @@ def my_redoc():
 ```
 
 
-## Disable the API documentations globally
+## Disable the API documentation globally
 
-You can set the `docs_path` parameter to `None` to disable Swagger UI documentation:
+You can set the `docs_path` parameter to `None` to disable the API documentation:
 
 ```python
 from apiflask import APIFlask
@@ -156,22 +156,27 @@ See *[Disable the OpenAPI support for specific blueprints](/openapi/#disable-for
 See *[Disable the OpenAPI support for specific view functions](/openapi/#disable-for-specific-view-functions)* for more details.
 
 
-## Configure Swagger UI/Redoc
+## Configure API documentations
 
-The following configuration variables can be used to config Swagger UI/Redoc:
+The following configuration variables can be used to configure API docs:
 
 - `DOCS_FAVICON`
 - `REDOC_USE_GOOGLE_FONT`
 - `REDOC_CONFIG`
 - `SWAGGER_UI_LAYOUT`
 - `SWAGGER_UI_CONFIG`
 - `SWAGGER_UI_OAUTH_CONFIG`
+- `ELEMENTS_LAYOUT`
+- `ELEMENTS_CONFIG`
+- `RAPIDOC_THEME`
+- `RAPIDOC_CONFIG`
+- `RAPIPDF_CONFIG`
 
-See *[Configuration](/configuration/#api-documentation)* for the
+See *[Configuration](/configuration/#api-documentations)* for the
 introduction and examples of these configuration variables.
 
 
-## Use different CDN server for Swagger UI/Redoc resources
+## Use different CDN server for API documentation resources
 
 Each resource (JavaScript/CSS files) URL has a configuration variable. You can pass
 the URL from your preferred CDN server to the corresponding configuration variables:
@@ -207,7 +212,7 @@ See *[Configuration](/configuration/#api-documentations)* for the
 introduction and examples of these configuration variables.
 
 
-## Serve Swagger UI/Redoc from local resources
+## Serve API documentation from local resources
 
 Like what you need to do in the last section, to use local resources, you can pass
 the URL of local static files to the corresponding configuration variables:

diff --git a/docs/authentication.md b/docs/authentication.md
@@ -47,8 +47,8 @@ Then you can set the security scheme with the `security` parameter in `app.doc()
 ```python hl_lines="5"
 @app.post('/pets')
 @my_auth_lib.protect  # protect the view with the decorator provided by external authentication library
-@app.input(PetInSchema)
-@app.output(PetOutSchema, 201)
+@app.input(PetIn)
+@app.output(PetOut, status_code=201)
 @app.doc(security='ApiKeyAuth')
 def create_pet(data):
     pet_id = len(pets)

diff --git a/docs/comparison.md b/docs/comparison.md
@@ -13,14 +13,16 @@ differences between APIFlask and similar projects.
 ## APIFlask vs FastAPI
 
 - For the web part, FastAPI builds on top of Starlette, while APIFlask builts on top of
-Flask.
+  Flask.
 - For the data part (serialization/deserialization, OpenAPI support), FastAPI relies
-on Pydantic, while APIFlask uses marshmallow-code projects (marshmallow, webargs, apispec).
+  on Pydantic, while APIFlask uses marshmallow-code projects (marshmallow, webargs, apispec).
 - APIFlask builds on top of Flask, so it's compatible with Flask extensions.
 - FastAPI support async. APIFlask will have the basic async support with Flask 2.0.
 - APIFlask provides more decorators to help organize things better.
 - FastAPI injects the input data as an object, while APIFlask passes it as a dict.
 - APIFlask has built-in class-based views support based on Flask's `MethodView`.
+- On top of Swagger UI and Redoc, APIFlask supports more API documentation tools:
+  Elements, RapiDoc, and RapiPDF.
 
 
 ## APIFlask vs APIFairy/flask-smorest
@@ -68,8 +70,8 @@ Assume a view like this:
 
 ```python
 @app.get('/<category>/articles/<int:article_id>')  # category, article_id
-@app.input(ArticleQuerySchema, location='query')  # query
-@app.input(ArticleInSchema)  # data
+@app.input(ArticleQuery, location='query')  # query
+@app.input(ArticleIn)  # data
 def get_article(category, article_id, query, data):
     pass
 ```

diff --git a/docs/configuration.md b/docs/configuration.md
@@ -99,7 +99,7 @@ Read more about configuration management in
 
     from .settings import CATEGORIES  # import the configuration variable
 
-    class PetInSchema(Schema):
+    class PetIn(Schema):
         name = String(required=True, validate=Length(0, 10))
         category = String(required=True, validate=OneOf(CATEGORIES))  # use it
     ```
@@ -801,12 +801,12 @@ from apiflask.fields import String, Integer, Field
 
 app = APIFlask(__name__)
 
-class BaseResponseSchema(Schema):
+class BaseResponse(Schema):
     message = String()
     status_code = Integer()
     data = Field()
 
-app.config['BASE_RESPONSE_SCHEMA'] = BaseResponseSchema
+app.config['BASE_RESPONSE_SCHEMA'] = BaseResponse
 ```
 
 !!! warning "Version >= 0.9.0"
@@ -832,9 +832,9 @@ app.config['BASE_RESPONSE_DATA_KEY'] = 'data'
     This configuration variable was added in the [version 0.9.0](/changelog/#version-090).
 
 
-## API documentations
+## API documentation
 
-The following configuration variables used to customize API documentations.
+The following configuration variables used to customize API documentation.
 
 
 ### DOCS_FAVICON

diff --git a/docs/docs.md b/docs/docs.md
@@ -22,7 +22,7 @@ Go through the following chapters to learn how to use APIFlask:
 - **[OpenAPI Generating](/openapi)**: Introduce how the OpenAPI generation works and how to customize
 it with `@app.doc` decorator and configuration variables.
 - **[Authentication](/authentication)**: Introduce how to implement authentication support for your application.
-- **[Swagger UI and Redoc](/api-docs)**: Introduce the usage and configuration of the API
+- **[API Documentation](/api-docs)**: Introduce the usage and configuration of the API
 documentation tools.
 - **[Configuration](/configuration)**: A list of all the built-in configuration variables
 - **[Examples](/examples)**: A collection of application examples.

diff --git a/docs/error-handling.md b/docs/error-handling.md
@@ -15,7 +15,7 @@ The error handling in APIFlask is based on the following basic concepts:
 !!! tip
 
     The error handler registered with `app.errorhandler` for specific HTTP errors will be
-    used over the custom error response processor.
+    used over the custom error response processor registered with `app.error_processor`.
 
 
 ## Automatic JSON error response
@@ -253,9 +253,9 @@ so you can get error information via its attributes:
     ...
     ```
 
-    The value of `location` can be `json` (i.e., request body) or `query`
-    (i.e., query string) depending on the place where the validation error
-    happened.
+    The value of `location` can be `json` (i.e., request body), `query`
+    (i.e., query string) or other values depending on the place where the
+    validation error happened (it matches the value you passed in `app.input`).
 
 - headers: The value will be `{}` unless you pass it in `HTTPError` or `abort`.
 - extra_data: Additional error information passed with `HTTPError` or `abort`.
@@ -275,7 +275,7 @@ def my_error_processor(error):
 
 !!! tip
 
-    I would recommend keeping the `detail` in the response since it contains
+    I would recommend keeping the `error.detail` data in the response since it contains
     the detailed information about the validation error when it happened.
 
 After you change the error response, you have to update the corresponding OpenAPI schema

diff --git a/docs/migrating.md b/docs/migrating.md
@@ -90,21 +90,21 @@ class Pet(MethodView):
 
     decorators = [doc(responses=[404])]
 
-    @app.output(PetOutSchema)
+    @app.output(PetOut)
     def get(self, pet_id):
         pass
 
-    @app.output({}, 204)
+    @app.output({}, status_code=204)
     def delete(self, pet_id):
         pass
 
-    @app.input(PetInSchema)
-    @app.output(PetOutSchema)
+    @app.input(PetIn)
+    @app.output(PetOut)
     def put(self, pet_id, data):
         pass
 
-    @app.input(PetInSchema(partial=True))
-    @app.output(PetOutSchema)
+    @app.input(PetIn(partial=True))
+    @app.output(PetOut)
     def patch(self, pet_id, data):
         pass
 ```