marshmallow-code / marshmallow-code/apispec

Document "content" parameters

Open
#922 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

backwards incompat feedback welcome
Dominant language
Python
Stars
1.2k
Forks
202
Avg merge
3h 38m
Merged PRs (30d)
3

Description

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`:

```py
def _field2parameter(
self, field: marshmallow.fields.Field, *, name: str, location: str
) -> dict:
"""Return an OpenAPI parameter as a `dict`, given a marshmallow
:class:`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`:

```py
[...]
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.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with `_field2parameter` and the `parameter_attribute_functions` customization introduced in #778. Determine how parameter fields should represent OpenAPI `content` while preserving existing schema behavior and customization compatibility. Done means JSON-object parameters can emit an appropriate content entry and the affected behavior is covered by the project’s tests.

Written by the indexing model from the issue text.

Assessment

Tech stack
openapi, python
Domain
api, documentation
Issue type
Feature
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.