From cecc326bdca10c5c5314a892ecdceafd5c9f693c Mon Sep 17 00:00:00 2001
From: Sanjay Santhanam <51058514+Sanjays2402@users.noreply.github.com>
Date: Sun, 4 Oct 2026 17:19:10 -0700
Subject: [PATCH 1/2] Document JSON query parameters using explicit content
 components

---
 docs/special_topics.rst | 68 +++++++++++++++++++++++++++++++++++++++++
 1 file changed, 68 insertions(+)

diff --git a/docs/special_topics.rst b/docs/special_topics.rst
index 19cfacbf..7fea65c0 100644
--- a/docs/special_topics.rst
+++ b/docs/special_topics.rst
@@ -23,6 +23,74 @@ to the ``component`` parameter. If your'e using ``MarshmallowPlugin``, the ``com
 .. note::
     Be careful about the input that you pass to ``component``. ``apispec`` will not guarantee that the passed fields are valid against the OpenAPI spec.
 
+Documenting JSON Query Parameters
+---------------------------------
+
+OpenAPI 3 allows a parameter to use ``content`` instead of ``schema`` when its
+value is serialized using a media type. For example, a query parameter can
+contain a JSON object rather than individual query parameters for each field.
+The `Parameter Object <https://spec.openapis.org/oas/v3.0.3#parameter-object>`_
+requires exactly one of ``schema`` or ``content``, and ``content`` must contain
+only one media type.
+
+To document this with apispec, pass a parameter dictionary to
+`spec.components.parameter <apispec.core.Components.parameter>` and reference
+it from an operation. A schema registered with ``MarshmallowPlugin`` can be
+referenced inside the media type's ``schema`` using its component name:
+
+.. code-block:: python
+
+    from apispec import APISpec
+    from apispec.ext.marshmallow import MarshmallowPlugin
+    from marshmallow import Schema, fields
+
+    class FilterSchema(Schema):
+        name = fields.String()
+        limit = fields.Integer()
+
+    spec = APISpec(
+        title="Search API",
+        version="1.0.0",
+        openapi_version="3.0.3",
+        plugins=[MarshmallowPlugin()],
+    )
+    spec.components.schema("Filter", schema=FilterSchema)
+    spec.components.parameter(
+        "SearchFilter",
+        "query",
+        {
+            "name": "filter",
+            "description": "A JSON-encoded search filter",
+            "content": {
+                "application/json": {
+                    "schema": "Filter",
+                    "example": {"name": "Ada", "limit": 10},
+                }
+            },
+        },
+    )
+    spec.path(
+        path="/search",
+        operations={
+            "get": {
+                "parameters": ["SearchFilter"],
+                "responses": {"200": {"description": "Search results"}},
+            }
+        },
+    )
+
+The generated parameter contains
+``content.application/json.schema.$ref: '#/components/schemas/Filter'`` and no
+top-level ``schema``. The operation references
+``#/components/parameters/SearchFilter``. Clients send the JSON value in the
+``filter`` query parameter with the usual URL encoding.
+
+``MarshmallowPlugin`` generates ``schema``-based parameters when a schema is
+passed directly to an operation's ``parameters``. Use an explicit parameter
+dictionary as above when documenting ``content``. This example describes the
+API contract; apispec does not deserialize the query parameter. OpenAPI 2 does
+not support parameter ``content``.
+
 Rendering to YAML or JSON
 -------------------------
 

From 56f060b82e8554cb7393f6f5e8bef2d65f4b5d2d Mon Sep 17 00:00:00 2001
From: "pre-commit-ci[bot]"
 <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Date: Mon, 5 Oct 2026 00:23:33 +0000
Subject: [PATCH 2/2] [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci
---
 docs/special_topics.rst | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/docs/special_topics.rst b/docs/special_topics.rst
index 7fea65c0..bd034129 100644
--- a/docs/special_topics.rst
+++ b/docs/special_topics.rst
@@ -44,10 +44,12 @@ referenced inside the media type's ``schema`` using its component name:
     from apispec.ext.marshmallow import MarshmallowPlugin
     from marshmallow import Schema, fields
 
+
     class FilterSchema(Schema):
         name = fields.String()
         limit = fields.Integer()
 
+
     spec = APISpec(
         title="Search API",
         version="1.0.0",