feat: add list_as_array flag to MarshmallowPlugin for array-root requestBody

AUTHORS.rst

@@ -87,3 +87,4 @@ Contributors (chronological)
 - Robert Shepley `@ShepleySound <https://github.com/ShepleySound>`_
 - Robin `@allrob23 <https://github.com/allrob23>`_
 - Xingang Zhang `@0x0400 <https://github.com/0x0400>`_
+- nomi3 `@nomi3 <https://github.com/nomi3>`_

src/apispec/ext/marshmallow/__init__.py

@@ -120,13 +120,15 @@ def schema_name_resolver(schema):
     def __init__(
         self,
         schema_name_resolver: typing.Callable[[type[Schema]], str] | None = None,
+        list_as_array: bool = False,
     ) -> None:
         super().__init__()
         self.schema_name_resolver = schema_name_resolver or resolver
         self.spec: APISpec | None = None
         self.openapi_version: Version | None = None
         self.converter: OpenAPIConverter | None = None
         self.resolver: SchemaResolver | None = None
+        self.list_as_array = list_as_array
 
     def init_spec(self, spec: APISpec) -> None:
         super().init_spec(spec)
@@ -136,6 +138,7 @@ def init_spec(self, spec: APISpec) -> None:
             openapi_version=spec.openapi_version,
             schema_name_resolver=self.schema_name_resolver,
             spec=spec,
+            list_as_array=self.list_as_array,
         )
         self.resolver = self.Resolver(
             openapi_version=spec.openapi_version, converter=self.converter

src/apispec/ext/marshmallow/openapi.py

@@ -56,6 +56,7 @@ def __init__(
         openapi_version: Version | str,
         schema_name_resolver,
         spec: APISpec,
+        list_as_array: bool = False,
     ) -> None:
         self.openapi_version = (
             Version(openapi_version)
@@ -66,6 +67,7 @@ def __init__(
         self.spec = spec
         self.init_attribute_functions()
         self.init_parameter_attribute_functions()
+        self.list_as_array = list_as_array
         # Schema references
         self.refs: dict = {}
 
@@ -108,6 +110,28 @@ def resolve_nested_schema(self, schema):
 
         :param schema: schema to add to the spec
         """
+        if isinstance(schema, marshmallow.fields.List) and self.list_as_array:
+            return {
+                "type": "array",
+                "items": self.resolve_nested_schema(schema.inner),
+            }
+
+        if self.list_as_array:
+            if isinstance(schema, marshmallow.Schema):
+                field_dict = schema.fields
+            elif isinstance(schema, type) and issubclass(schema, marshmallow.Schema):
+                field_dict = schema._declared_fields
+            else:
+                field_dict = None
+
+            if field_dict is not None and len(field_dict) == 1:
+                fld = next(iter(field_dict.values()))
+                if isinstance(fld, marshmallow.fields.List) and fld.data_key is None:
+                    return {
+                        "type": "array",
+                        "items": self.resolve_nested_schema(fld.inner),
+                    }
+
         try:
             schema_instance = resolve_schema_instance(schema)
         # If schema is a string and is not found in registry,

tests/test_array_requestbody.py

@@ -0,0 +1,49 @@
+from marshmallow import Schema, fields
+
+from apispec import APISpec
+from apispec.ext.marshmallow import MarshmallowPlugin
+
+
+class UUIDListSchema(Schema):
+    uuids = fields.List(fields.UUID(), data_key=None)
+
+
+def _build_schema(list_as_array: bool):
+    plugin = MarshmallowPlugin(list_as_array=list_as_array)
+    spec = APISpec(
+        title="Test",
+        version="1.0.0",
+        openapi_version="3.0.2",
+        plugins=[plugin],
+    )
+    spec.path(
+        path="/list",
+        operations={
+            "post": {
+                "requestBody": {
+                    "content": {"application/json": {"schema": UUIDListSchema()}}
+                },
+                "responses": {"200": {}},
+            }
+        },
+    )
+    schema = spec.to_dict()["paths"]["/list"]["post"]["requestBody"]["content"][
+        "application/json"
+    ]["schema"]
+
+    if "$ref" in schema:
+        ref_name = schema["$ref"].split("/")[-1]
+        schema = spec.to_dict()["components"]["schemas"][ref_name]
+
+    return schema
+
+
+def test_default_is_object():
+    schema = _build_schema(list_as_array=False)
+    assert schema["type"] == "object"
+
+
+def test_list_as_array_flag():
+    schema = _build_schema(list_as_array=True)
+    assert schema["type"] == "array"
+    assert "items" in schema