Document "content" parameters

Đang mở
  • Có gì không ổn?
#922 0 bình luận 0 reaction 0 người được giao Xem trên GitHub

Maintainer thường phản hồi trong vòng 1 ngày

@Sanjays2402 đang làm issue này rồi.

Từ ngày 5/10/2026.

  • #1078 của @Sanjays2402 — đang mở

Đánh giá

Độ khó
4/5
Thời gian dự kiến
3-5 ngày
Mức phù hợp với người mới
45/100
Loại issue
Tính năng
Độ rõ ràng
Khá rõ ràng
Mức độ hoạt động
Đình trệ
Công nghệ
openapi, python
Lĩnh vực
api, documentation

Hướng nghiên cứu

Bắt đầu với _field2parameter và tùy biến parameter_attribute_functions được giới thiệu trong #778. Xác định cách các trường tham số nên biểu diễn content của OpenAPI đồng thời duy trì hành vi schema hiện có và khả năng tương thích với tùy biến. Hoàn thành khi các tham số đối tượng JSON có thể phát ra một mục content phù hợp và hành vi bị ảnh hưởng được các bài kiểm thử của dự án bao phủ.

Do mô hình lập chỉ mục viết ra từ nội dung của issue.

Mô tả

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.

Ngôn ngữ chính
Python
Star
1.2k
Fork
210
Merge trung bình
2 ngày 1 giờ
Pull request đã merge (30 ngày)
4

Chuẩn bị môi trường

Bắt đầu từ đâu

  1. Đọc hết issue, rồi đọc hướng dẫn đóng góp của dự án.
  2. Bình luận trên issue rằng bạn sẽ nhận — tránh hai người làm cùng một việc.
  3. Fork repository và làm thay đổi trên một nhánh.
  4. Mở pull request có tham chiếu số hiệu của issue.

Issue khác của marshmallow-code/apispec

Tất cả issue của marshmallow-code/apispec

Issue tương tự

Thêm issue về Python

Nhận issue mới trong hộp thư của bạn

Bản tóm tắt ngắn những issue GitHub phù hợp với người mới.