Document "content" parameters

[lafrech]

https://swagger.io/docs/specification/describing-parameters/

To describe the parameter contents, you can use either the schema or content keyword.
[...]
content is used in complex serialization scenarios that are not covered by style and explode.

apispec assumes schema:

    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}

        prop = self.field2property(field)
        if self.openapi_version.major < 3:
            ret.update(prop)
        else:
            if "description" in prop:
                ret["description"] = prop.pop("description")
            if "deprecated" in prop:
                ret["deprecated"] = prop.pop("deprecated")
            ret["schema"] = prop  # <------------------------ here

        for param_attr_func in self.parameter_attribute_functions:
            ret.update(param_attr_func(field, ret=ret))

        return ret

In my code, I had to override that method to document a field that expects a JSON object and deserializes it into a dict:

            [...]
            ret["schema"] = prop

        if isinstance(field, DictStr):
            ret["content"] = {"application/json": {"schema": ret.pop("schema")}}

        for param_attr_func in self.parameter_attribute_functions:
            ret.update(param_attr_func(field, ret=ret))

        return ret

We already added parameter_attribute_functions in #778 for specific cases that couldn't be addressed in field2property. Unfortunately, those functions only add stuff to the doc (their return value is fed to ret.update), so they can't do what is required above.

We could change that to let parameter attribute functions mutate ret for more customization (breaking change). It makes me cringe a bit because if several functions apply to the same field, they may interfere with each other and cause a crash. But after all, we're all grown-ups and I expect those kinds of exceptions to be scarce, so it shouldn't be an issue.

I'll try to carve some time to investigate this. Meanwhile, better ideas welcome.