marshmallow ext OpenAPIConverter: add add_parameter_attribute_function

Author: lafrech

src/apispec/ext/marshmallow/openapi.py

@@ -8,6 +8,7 @@
 """
 
 from __future__ import annotations
+import typing
 
 import marshmallow
 from marshmallow.utils import is_collection
@@ -59,9 +60,37 @@ def __init__(
         self.schema_name_resolver = schema_name_resolver
         self.spec = spec
         self.init_attribute_functions()
+        self.init_parameter_attribute_functions()
         # Schema references
         self.refs: dict = {}
 
+    def init_parameter_attribute_functions(self) -> None:
+        self.parameter_attribute_functions = [
+            self.field2required,
+            self.list2param,
+        ]
+
+    def add_parameter_attribute_function(self, func) -> None:
+        """Method to add a field parameter function to the list of field
+        parameter functions that will be called on a field to convert it to a
+        field parameter.
+
+        :param func func: the field parameter function to add
+            The attribute function will be bound to the
+            `OpenAPIConverter <apispec.ext.marshmallow.openapi.OpenAPIConverter>`
+            instance.
+            It will be called for each field in a schema with
+            `self <apispec.ext.marshmallow.openapi.OpenAPIConverter>` and a
+            `field <marshmallow.fields.Field>` instance
+            positional arguments and `ret <dict>` keyword argument.
+            May mutate `ret`.
+            User added field parameter functions will be called after all built-in
+            field parameter functions in the order they were added.
+        """
+        bound_func = func.__get__(self)
+        setattr(self, func.__name__, bound_func)
+        self.parameter_attribute_functions.append(bound_func)
+
     def resolve_nested_schema(self, schema):
         """Return the OpenAPI representation of a marshmallow Schema.
 
@@ -150,30 +179,52 @@ def schema2parameters(
 
     def _field2parameter(
         self, field: marshmallow.fields.Field, *, name: str, location: str
-    ):
+    ) -> dict:
         """Return an OpenAPI parameter as a `dict`, given a marshmallow
         :class:`Field <marshmallow.Field>`.
 
         https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#parameterObject
         """
         ret: dict = {"in": location, "name": name}
 
-        partial = getattr(field.parent, "partial", False)
-        ret["required"] = field.required and (
-            not partial
-            or (is_collection(partial) and field.name not in partial)  # type:ignore
-        )
-
         prop = self.field2property(field)
         if self.openapi_version.major < 3:
             ret.update(prop)
         else:
-            if prop.get("description", None):
+            if "description" in prop:
                 ret["description"] = prop.pop("description")
             ret["schema"] = prop
 
-        multiple = isinstance(field, marshmallow.fields.List)
-        if multiple:
+        for param_attr_func in self.parameter_attribute_functions:
+            ret.update(param_attr_func(field, ret=ret))
+
+        return ret
+
+    def field2required(
+        self, field: marshmallow.fields.Field, **kwargs: typing.Any
+    ) -> dict:
+        """Return the dictionary of OpenAPI parameter attributes for a required field.
+
+        :param Field field: A marshmallow field.
+        :rtype: dict
+        """
+        ret = {}
+        partial = getattr(field.parent, "partial", False)
+        ret["required"] = field.required and (
+            not partial
+            or (is_collection(partial) and field.name not in partial)  # type:ignore
+        )
+        return ret
+
+    def list2param(self, field: marshmallow.fields.Field, **kwargs: typing.Any) -> dict:
+        """Return a dictionary of parameter properties from
+        :class:`List <marshmallow.fields.List` fields.
+
+        :param Field field: A marshmallow field.
+        :rtype: dict
+        """
+        ret: dict = {}
+        if isinstance(field, marshmallow.fields.List):
             if self.openapi_version.major < 3:
                 ret["collectionFormat"] = "multi"
             else:

tests/test_ext_marshmallow_openapi.py

@@ -207,20 +207,36 @@ class NotASchema:
 
 
 class TestMarshmallowSchemaToParameters:
-    @pytest.mark.parametrize("ListClass", [fields.List, CustomList])
-    def test_field_multiple(self, ListClass, openapi):
-        field = ListClass(fields.Str)
-        res = openapi._field2parameter(field, name="field", location="query")
-        assert res["in"] == "query"
-        if openapi.openapi_version.major < 3:
-            assert res["type"] == "array"
-            assert res["items"]["type"] == "string"
-            assert res["collectionFormat"] == "multi"
+    def test_custom_properties_for_custom_fields(self, spec_fixture):
+        class DelimitedList(fields.List):
+            """Delimited list field"""
+
+        def delimited_list2param(self, field, **kwargs):
+            ret: dict = {}
+            if isinstance(field, DelimitedList):
+                if self.openapi_version.major < 3:
+                    ret["collectionFormat"] = "csv"
+                else:
+                    ret["explode"] = False
+                    ret["style"] = "form"
+            return ret
+
+        spec_fixture.marshmallow_plugin.converter.add_parameter_attribute_function(
+            delimited_list2param
+        )
+
+        class MySchema(Schema):
+            delimited_list = DelimitedList(fields.Int)
+
+        param = spec_fixture.marshmallow_plugin.converter.schema2parameters(
+            MySchema(), location="query"
+        )[0]
+
+        if spec_fixture.openapi.openapi_version.major < 3:
+            assert param["collectionFormat"] == "csv"
         else:
-            assert res["schema"]["type"] == "array"
-            assert res["schema"]["items"]["type"] == "string"
-            assert res["style"] == "form"
-            assert res["explode"] is True
+            assert param["explode"] is False
+            assert param["style"] == "form"
 
     def test_field_required(self, openapi):
         field = fields.Str(required=True)
@@ -252,6 +268,21 @@ class UserSchema(Schema):
         param = next(p for p in res_nodump if p["name"] == "partial_field")
         assert param["required"] is False
 
+    @pytest.mark.parametrize("ListClass", [fields.List, CustomList])
+    def test_field_list(self, ListClass, openapi):
+        field = ListClass(fields.Str)
+        res = openapi._field2parameter(field, name="field", location="query")
+        assert res["in"] == "query"
+        if openapi.openapi_version.major < 3:
+            assert res["type"] == "array"
+            assert res["items"]["type"] == "string"
+            assert res["collectionFormat"] == "multi"
+        else:
+            assert res["schema"]["type"] == "array"
+            assert res["schema"]["items"]["type"] == "string"
+            assert res["style"] == "form"
+            assert res["explode"] is True
+
     # json/body is invalid for OpenAPI 3
     @pytest.mark.parametrize("openapi", ("2.0",), indirect=True)
     def test_schema_body(self, openapi):