Document "content" parameters

Abierto
  • ¿Algo no está bien?
#922 0 comentarios 0 reacciones 0 asignados Ver en GitHub

Los mantenedores suelen responder en 1 día

@Sanjays2402 ya está trabajando en esto.

Desde el 5/10/2026.

  • #1078 de @Sanjays2402 — abierto

Evaluación

Dificultad
4/5
Tiempo estimado
3-5 días
Aptitud para principiantes
45/100
Tipo de issue
Nueva funcionalidad
Claridad
Bastante claro
Estado de actividad
Estancado
Stack tecnológico
openapi, python
Área
api, documentation

Línea de trabajo

Comienza con _field2parameter y la personalización parameter_attribute_functions introducida en #778. Determina cómo deben representar los campos de parámetros el content de OpenAPI, conservando el comportamiento existente de los esquemas y la compatibilidad con la personalización. Se considera terminado cuando los parámetros de objetos JSON puedan emitir una entrada de content adecuada y el comportamiento afectado esté cubierto por las pruebas del proyecto.

Escrito por el modelo de indexación a partir del texto del issue.

Descripción

backwards incompat feedback welcome

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.

Lenguaje dominante
Python
Estrellas
1.2k
Forks
210
Merge medio
2 d 1 h
PR fusionados (30 d)
4

Preparar el entorno

Primeros pasos

  1. Lee el issue completo y luego la guía de contribución del proyecto.
  2. Comenta en el issue que vas a ocuparte — evita que dos personas hagan lo mismo.
  3. Haz un fork del repositorio y trabaja en una rama.
  4. Abre un pull request que haga referencia al número del issue.

Más de marshmallow-code/apispec

Todos los issues de marshmallow-code/apispec

Issues similares

Más issues de Python

Recibe los nuevos issues en tu correo

Un resumen breve de issues de GitHub para principiantes.