Support returning lists of unserialized models

Makefile

@@ -45,7 +45,7 @@ format:
 lint:
 	isort --check --diff --project=spectree ${SOURCE_FILES}
 	black --check --diff ${SOURCE_FILES}
-	flake8 ${SOURCE_FILES} --count --show-source --statistics --ignore=D203,E203,W503 --max-line-length=88 --max-complexity=15
+	flake8 ${SOURCE_FILES} --count --show-source --statistics --ignore=D203,E203,W503 --max-line-length=88 --max-complexity=16
 	mypy --install-types --non-interactive ${MYPY_SOURCE_FILES}
 
 .PHONY: test doc

spectree/_types.py

@@ -8,14 +8,16 @@
     Optional,
     Sequence,
     Type,
+    TypeVar,
     Union,
 )
 
 from typing_extensions import Protocol
 
 from ._pydantic import BaseModel
 
-ModelType = Type[BaseModel]
+BaseModelSubclassType = TypeVar("BaseModelSubclassType", bound=BaseModel)
+ModelType = Type[BaseModelSubclassType]
 OptionalModelType = Optional[ModelType]
 NamingStrategy = Callable[[ModelType], str]
 NestedNamingStrategy = Callable[[str, str], str]

spectree/plugins/falcon_plugin.py

@@ -6,7 +6,7 @@
 from falcon import HTTP_400, HTTP_415, HTTPError
 from falcon.routing.compiled import _FIELD_PATTERN as FALCON_FIELD_PATTERN
 
-from .._pydantic import ValidationError
+from .._pydantic import BaseModel, ValidationError
 from .._types import ModelType
 from ..response import Response
 from .base import BasePlugin
@@ -227,17 +227,24 @@ def validate(
         func(*args, **kwargs)
 
         if resp and resp.has_model():
-            model = resp.find_model(_resp.status[:3])
-            if model and isinstance(_resp.media, model):
-                _resp.media = _resp.media.dict()
+            model = _resp.media
+            status = int(_resp.status[:3])
+            expect_model = resp.find_model(status)
+            if resp.expect_list_result(status) and isinstance(model, list):
+                _resp.media = [
+                    (entry.dict() if isinstance(entry, BaseModel) else entry)
+                    for entry in model
+                ]
+            elif expect_model and isinstance(_resp.media, expect_model):
+                _resp.media = model.dict()
                 skip_validation = True
 
             if self._data_set_manually(_resp):
                 skip_validation = True
 
-            if model and not skip_validation:
+            if expect_model and not skip_validation:
                 try:
-                    model.parse_obj(_resp.media)
+                    expect_model.parse_obj(_resp.media)
                 except ValidationError as err:
                     resp_validation_error = err
                     _resp.status = HTTP_500

spectree/plugins/flask_plugin.py

@@ -210,7 +210,16 @@ def validate(
 
         if resp:
             expect_model = resp.find_model(status)
-            if expect_model and isinstance(model, expect_model):
+            if resp.expect_list_result(status) and isinstance(model, list):
+                result = (
+                    [
+                        (entry.dict() if isinstance(entry, BaseModel) else entry)
+                        for entry in model
+                    ],
+                    status,
+                    *rest,
+                )
+            elif expect_model and isinstance(model, expect_model):
                 skip_validation = True
                 result = (model.dict(), status, *rest)
 

spectree/plugins/quart_plugin.py

@@ -222,6 +222,15 @@ async def validate(
 
         if resp:
             expect_model = resp.find_model(status)
+            if resp.expect_list_result(status) and isinstance(model, list):
+                result = (
+                    [
+                        (entry.dict() if isinstance(entry, BaseModel) else entry)
+                        for entry in model
+                    ],
+                    status,
+                    *rest,
+                )
             if expect_model and isinstance(model, expect_model):
                 skip_validation = True
                 result = (model.dict(), status, *rest)

spectree/plugins/starlette_plugin.py

@@ -9,7 +9,7 @@
 from starlette.responses import HTMLResponse, JSONResponse
 from starlette.routing import compile_path
 
-from .._pydantic import ValidationError
+from .._pydantic import BaseModel, ValidationError
 from .._types import ModelType
 from ..response import Response
 from .base import BasePlugin, Context
@@ -22,7 +22,14 @@ def PydanticResponse(content):
     class _PydanticResponse(JSONResponse):
         def render(self, content) -> bytes:
             self._model_class = content.__class__
-            return super().render(content.dict())
+            return super().render(
+                [
+                    (entry.dict() if isinstance(entry, BaseModel) else entry)
+                    for entry in content
+                ]
+                if isinstance(content, list)
+                else content.dict()
+            )
 
     return _PydanticResponse(content)
 

spectree/response.py

@@ -1,8 +1,8 @@
 from http import HTTPStatus
-from typing import Any, Dict, Iterable, List, Optional, Tuple, Union
+from typing import Any, Dict, Iterable, List, Optional, Set, Tuple, Type, Union
 
 from ._pydantic import BaseModel
-from ._types import ModelType, NamingStrategy, OptionalModelType
+from ._types import BaseModelSubclassType, ModelType, NamingStrategy, OptionalModelType
 from .utils import gen_list_model, get_model_key, parse_code
 
 # according to https://tools.ietf.org/html/rfc2616#section-10
@@ -30,22 +30,30 @@ class Response:
 
     examples:
 
+        >>> from typing import List
         >>> from spectree.response import Response
         >>> from pydantic import BaseModel
         ...
         >>> class User(BaseModel):
         ...     id: int
         ...
-        >>> response = Response(HTTP_200)
+        >>> response = Response("HTTP_200")
         >>> response = Response(HTTP_200=None)
         >>> response = Response(HTTP_200=User)
         >>> response = Response(HTTP_200=(User, "status code description"))
+        >>> response = Response(HTTP_200=List[User])
+        >>> response = Response(HTTP_200=(List[User], "status code description"))
     """
 
     def __init__(
         self,
         *codes: str,
-        **code_models: Union[OptionalModelType, Tuple[OptionalModelType, str]],
+        **code_models: Union[
+            OptionalModelType,
+            Tuple[OptionalModelType, str],
+            Type[List[BaseModelSubclassType]],
+            Tuple[Type[List[BaseModelSubclassType]], str],
+        ],
     ) -> None:
         self.codes: List[str] = []
 
@@ -55,6 +63,7 @@ def __init__(
 
         self.code_models: Dict[str, ModelType] = {}
         self.code_descriptions: Dict[str, Optional[str]] = {}
+        self.codes_expecting_list_result: Set[str] = set()
         for code, model_and_description in code_models.items():
             assert code in DEFAULT_CODE_DESC, "invalid HTTP status code"
             description: Optional[str] = None
@@ -73,6 +82,7 @@ def __init__(
                 if origin_type is list or origin_type is List:
                     # type is List[BaseModel]
                     model = gen_list_model(getattr(model, "__args__")[0])
+                    self.codes_expecting_list_result.add(code)
                 assert issubclass(model, BaseModel), "invalid `pydantic.BaseModel`"
                 assert description is None or isinstance(
                     description, str
@@ -119,6 +129,13 @@ def find_model(self, code: int) -> OptionalModelType:
         """
         return self.code_models.get(f"HTTP_{code}")
 
+    def expect_list_result(self, code: int) -> bool:
+        """Check whether a specific HTTP code expects a list result.
+
+        :param code: Status code string, format('HTTP_[0-9]_{3}'), 'HTTP_200'.
+        """
+        return f"HTTP_{code}" in self.codes_expecting_list_result
+
     def get_code_description(self, code: str) -> str:
         """Get the description of the given status code.
 

tests/__snapshots__/test_plugin/test_plugin_spec[falcon][full_spec].json

@@ -67,6 +67,31 @@
         "title": "JSON",
         "type": "object"
       },
+      "JSONList.a9993e3": {
+        "items": {
+          "$ref": "#/components/schemas/JSONList.a9993e3.JSON"
+        },
+        "title": "JSONList",
+        "type": "array"
+      },
+      "JSONList.a9993e3.JSON": {
+        "properties": {
+          "limit": {
+            "title": "Limit",
+            "type": "integer"
+          },
+          "name": {
+            "title": "Name",
+            "type": "string"
+          }
+        },
+        "required": [
+          "name",
+          "limit"
+        ],
+        "title": "JSON",
+        "type": "object"
+      },
       "ListJSON.7068f62": {
         "items": {
           "$ref": "#/components/schemas/ListJSON.7068f62.JSON"
@@ -327,6 +352,37 @@
         "tags": []
       }
     },
+    "/api/return_list": {
+      "get": {
+        "description": "",
+        "operationId": "get__api_return_list",
+        "parameters": [],
+        "responses": {
+          "200": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/JSONList.a9993e3"
+                }
+              }
+            },
+            "description": "OK"
+          },
+          "422": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ValidationError.6a07bef"
+                }
+              }
+            },
+            "description": "Unprocessable Entity"
+          }
+        },
+        "summary": "on_get <GET>",
+        "tags": []
+      }
+    },
     "/api/user/{name}": {
       "get": {
         "description": "",

tests/__snapshots__/test_plugin/test_plugin_spec[flask][full_spec].json

@@ -85,6 +85,31 @@
         "title": "JSON",
         "type": "object"
       },
+      "JSONList.a9993e3": {
+        "items": {
+          "$ref": "#/components/schemas/JSONList.a9993e3.JSON"
+        },
+        "title": "JSONList",
+        "type": "array"
+      },
+      "JSONList.a9993e3.JSON": {
+        "properties": {
+          "limit": {
+            "title": "Limit",
+            "type": "integer"
+          },
+          "name": {
+            "title": "Name",
+            "type": "string"
+          }
+        },
+        "required": [
+          "name",
+          "limit"
+        ],
+        "title": "JSON",
+        "type": "object"
+      },
       "ListJSON.7068f62": {
         "items": {
           "$ref": "#/components/schemas/ListJSON.7068f62.JSON"
@@ -280,6 +305,37 @@
         "tags": []
       }
     },
+    "/api/return_list": {
+      "get": {
+        "description": "",
+        "operationId": "get__api_return_list",
+        "parameters": [],
+        "responses": {
+          "200": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/JSONList.a9993e3"
+                }
+              }
+            },
+            "description": "OK"
+          },
+          "422": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ValidationError.6a07bef"
+                }
+              }
+            },
+            "description": "Unprocessable Entity"
+          }
+        },
+        "summary": "return_list <GET>",
+        "tags": []
+      }
+    },
     "/api/user/{name}": {
       "post": {
         "description": "",