Improve mypy type hints

Author: luolingchun

docs/Usage/Route_Operation.md

@@ -1,4 +1,4 @@
-## tag
+## tags
 
 You can also specify tag for apis like this:
 
@@ -17,16 +17,17 @@ and then you will get the magic.
 
 ![image-20210525160744617](../assets/image-20210525160744617.png)
 
-### abp_tags
+## abp_tags & view_tags
 
 *New in v0.9.3*
 
-You don't need to specify **tag** for every api.
+You don't need to specify **tags** for every api.
 
-```python hl_lines="3"
+```python hl_lines="3 4"
 tag = Tag(name='book', description="Some Book")
 
 api = APIBlueprint('/book', __name__, url_prefix='/api', abp_tags=[tag])
+api_view = APIView('/book', __name__, url_prefix='/api', view_tags=[tag])
 
 
 @api.post('/book')
@@ -272,6 +273,24 @@ def get_book(path: BookPath):
     ...
 ```
 
+## abp_security & view_security
+
+*New in v0.9.3*
+
+You don't need to specify **security** for every api.
+
+```python hl_lines="3 4"
+tag = Tag(name='book', description="Some Book")
+security = [{"jwt": []}]
+api = APIBlueprint('/book', __name__, abp_tags=[tag], abp_security=security)
+api_view = APIView('/book', __name__, abp_tags=[tag], view_security=security)
+
+
+@api.post('/book')
+def create_book(body: BookBody):
+    ...
+```
+
 ## servers
 
 An array of Server Objects, which provide connectivity information to a target server. If the server's property is not provided, or is an empty array, the default value would be a Server Object with an url value of /.

docs/Usage/Specification.md

@@ -129,7 +129,7 @@ security = [{"jwt": []}]
 app = OpenAPI(__name__, info=info, security_schemes=security_schemes)
 ```
 
-Second, add pass the **security** to your api, like this:
+Second, add pass the [**security**](./Route_Operation.md#security) to your api, like this:
 
 ```python hl_lines="1"
 @app.get('/book/<int:bid>', tags=[book_tag], security=security)
@@ -141,22 +141,6 @@ result:
 
 ![image-20210525165350520](../assets/image-20210525165350520.png)
 
-### abp_security
-
-*New in v0.9.3*
-
-You don't need to specify **security** for every api.
-
-```python hl_lines="3"
-tag = Tag(name='book', description="Some Book")
-security = [{"jwt": []}]
-api = APIBlueprint('/book', __name__, abp_tags=[tag], abp_security=security)
-
-
-@api.post('/book')
-def create_book(body: BookBody):
-    ...
-```
 
 ## oauth_config
 
@@ -226,11 +210,11 @@ def endpoint():
     ...
 ```
 
-### abp_responses
+## abp_responses & view_responses
 
 *New in v0.9.4*
 
-You can add `responses` for each API under the `api` wrapper.
+You can add `responses` for each API under the `api` or `api_view` wrapper.
 
 ```python hl_lines="10"
 class Unauthorized(BaseModel):
@@ -239,10 +223,15 @@ class Unauthorized(BaseModel):
 
 
 api = APIBlueprint(
-    '/book', 
+    "/book", 
     __name__, 
-    url_prefix='/api',
-    abp_responses={"401": Unauthorized}
+    url_prefix="/api",
+    abp_responses={401: Unauthorized}
+)
+
+api_view = APIView(
+    "/book",
+    view_responses={401: Unauthorized}
 )
 
 @api.get(...)
@@ -262,15 +251,15 @@ You can also use [responses ](./Response.md#responses) and [extra_responses](./R
 
 ## doc_ui
 
-You can pass `doc_ui=False` to disable the `OpenAPI spec` when init `OpenAPI `.
+You can pass `doc_ui=False` to disable the `OpenAPI spec` when init [`OpenAPI`](../Reference/OpenAPI.md).
 
 ```python
 app = OpenAPI(__name__, info=info, doc_ui=False)
 ```
 
 *New in v0.9.4*
 
-You can also use `doc_ui` in endpoint or when initializing `APIBlueprint`.
+You can also use `doc_ui` in endpoint or when initializing [`APIBlueprint`](../Reference/APIBlueprint.md) or [`APIView`](../Reference/APIView.md).
 
 ```python hl_lines="4 9"
 api = APIBlueprint(

flask_openapi3/blueprint.py

@@ -2,17 +2,17 @@
 # @Author  : llc
 # @Time    : 2022/4/1 16:54
 from copy import deepcopy
-from typing import Optional, List, Dict, Any, Type, Callable, Tuple
+from typing import Optional, List, Dict, Any, Callable
 
 from flask import Blueprint
-from pydantic import BaseModel
 
 from ._http import HTTPMethod
 from .models import ExternalDocumentation
 from .models import ExtraRequestBody
 from .models import Server
 from .models import Tag
 from .scaffold import APIScaffold
+from .types import ParametersTuple
 from .types import ResponseDict
 from .utils import convert_responses_key_to_string
 from .utils import get_operation
@@ -119,7 +119,7 @@ def _do_decorator(
             openapi_extensions: Optional[Dict[str, Any]] = None,
             doc_ui: bool = True,
             method: str = HTTPMethod.GET
-    ) -> Tuple[Type[BaseModel], Type[BaseModel], Type[BaseModel], Type[BaseModel], Type[BaseModel], Type[BaseModel]]:
+    ) -> ParametersTuple:
         """
         Collects OpenAPI specification information for Flask routes and view functions.
 

flask_openapi3/models/__init__.py

@@ -41,8 +41,8 @@
 from .validation_error import ValidationErrorModel
 from .xml import XML
 
-OPENAPI3_REF_PREFIX = '#/components/schemas'
-OPENAPI3_REF_TEMPLATE = OPENAPI3_REF_PREFIX + '/{model}'
+OPENAPI3_REF_PREFIX = "#/components/schemas"
+OPENAPI3_REF_TEMPLATE = OPENAPI3_REF_PREFIX + "/{model}"
 
 
 class APISpec(BaseModel):

flask_openapi3/models/components.py

@@ -29,7 +29,7 @@ class Components(BaseModel):
     examples: Optional[Dict[str, Union[Example, Reference]]] = None
     requestBodies: Optional[Dict[str, Union[RequestBody, Reference]]] = None
     headers: Optional[Dict[str, Union[Header, Reference]]] = None
-    securitySchemes: Optional[Dict[str, Union[SecurityScheme, Any]]] = None
+    securitySchemes: Optional[Dict[str, Union[SecurityScheme, Dict[str, Any]]]] = None
     links: Optional[Dict[str, Union[Link, Reference]]] = None
     callbacks: Optional[Dict[str, Union[Callback, Reference]]] = None
     pathItems: Optional[Dict[str, Union[PathItem, Reference]]] = None

flask_openapi3/models/file.py

@@ -20,14 +20,8 @@ def __get_validators__(cls) -> Generator:
 
     @classmethod
     def __modify_schema__(cls, field_schema: Dict[str, Any]) -> None:
-        field_schema.update(
-            format="binary",
-            type="string"
-        )
+        field_schema.update(format="binary", type="string")
 
     @classmethod
-    def validate(cls, value: Any) -> '_FileStorage':
-        if not isinstance(value, _FileStorage):
-            raise TypeError('werkzeug.datastructures.FileStorage required')
-
+    def validate(cls, value: Any) -> "_FileStorage":
         return value

flask_openapi3/models/operation.py

@@ -10,7 +10,7 @@
 from .parameter import Parameter
 from .reference import Reference
 from .request_body import RequestBody
-from .responses import Responses
+from .response import Response
 from .security_requirement import SecurityRequirement
 from .server import Server
 
@@ -25,9 +25,9 @@ class Operation(BaseModel):
     description: Optional[str] = None
     externalDocs: Optional[ExternalDocumentation] = None
     operationId: Optional[str] = None
-    parameters: Optional[List[Union[Parameter, Reference]]] = None
+    parameters: Optional[List[Parameter]] = None
     requestBody: Optional[Union[RequestBody, Reference]] = None
-    responses: Optional[Responses] = None
+    responses: Optional[Dict[str, Response]] = None
     callbacks: Optional[Dict[str, Callback]] = None
 
     deprecated: Optional[bool] = False

flask_openapi3/openapi.py

@@ -5,7 +5,7 @@
 import os
 import re
 from copy import deepcopy
-from typing import Optional, List, Dict, Union, Any, Type, Callable, Tuple
+from typing import Optional, List, Dict, Union, Any, Type, Callable
 
 from flask import Flask, Blueprint, render_template_string
 from pydantic import BaseModel
@@ -29,6 +29,7 @@
 from .templates import rapidoc_html_string
 from .templates import redoc_html_string
 from .templates import swagger_html_string
+from .types import ParametersTuple
 from .types import ResponseDict
 from .types import SecuritySchemesDict
 from .utils import convert_responses_key_to_string
@@ -254,7 +255,7 @@ def api_doc(self) -> Dict:
 
         # Set components
         self.components.schemas = self.components_schemas
-        self.components.securitySchemes = self.security_schemes  # type: ignore
+        self.components.securitySchemes = self.security_schemes
         spec.components = self.components
 
         # Convert spec to JSON
@@ -356,7 +357,7 @@ def _do_decorator(
             openapi_extensions: Optional[Dict[str, Any]] = None,
             doc_ui: bool = True,
             method: str = HTTPMethod.GET
-    ) -> Tuple[Type[BaseModel], Type[BaseModel], Type[BaseModel], Type[BaseModel], Type[BaseModel], Type[BaseModel]]:
+    ) -> ParametersTuple:
         """
         Collects OpenAPI specification information for Flask routes and view functions.
 

flask_openapi3/scaffold.py

@@ -7,18 +7,18 @@
 import warnings
 from abc import ABC
 from functools import wraps
-from typing import Callable, List, Optional, Dict, Type, Any, Tuple
+from typing import Callable, List, Optional, Dict, Any
 
 from flask.scaffold import Scaffold
 from flask.wrappers import Response as FlaskResponse
-from pydantic import BaseModel
 
 from ._http import HTTPMethod
 from .models import ExternalDocumentation
 from .models import ExtraRequestBody
 from .models import Server
 from .models import Tag
 from .request import _do_request
+from .types import ParametersTuple
 from .types import ResponseDict
 
 if sys.version_info >= (3, 8):
@@ -57,7 +57,7 @@ def _do_decorator(
             openapi_extensions: Optional[Dict[str, Any]] = None,
             doc_ui: bool = True,
             method: str = HTTPMethod.GET
-    ) -> Tuple[Type[BaseModel], Type[BaseModel], Type[BaseModel], Type[BaseModel], Type[BaseModel], Type[BaseModel]]:
+    ) -> ParametersTuple:
         raise NotImplementedError
 
     def register_api(self, api) -> None:

flask_openapi3/types.py

@@ -2,12 +2,11 @@
 # @Author  : llc
 # @Time    : 2023/7/9 15:25
 from http import HTTPStatus
-from typing import Dict, Union, Type, Any
+from typing import Dict, Union, Type, Any, Tuple, Optional
 
 from pydantic import BaseModel
 
-# deprecated in v3.x
-from .models.security import SecurityScheme
+from .models import SecurityScheme
 
 _ResponseDictValue = Union[Type[BaseModel], Dict[Any, Any], None]
 
@@ -16,3 +15,12 @@
 ResponseStrKeyDict = Dict[str, _ResponseDictValue]
 
 SecuritySchemesDict = Dict[str, Union[SecurityScheme, Dict[str, Any]]]
+
+ParametersTuple = Tuple[
+    Optional[Type[BaseModel]],
+    Optional[Type[BaseModel]],
+    Optional[Type[BaseModel]],
+    Optional[Type[BaseModel]],
+    Optional[Type[BaseModel]],
+    Optional[Type[BaseModel]]
+]