From d1457fa12a77d91565ed86eb47708e786f581c61 Mon Sep 17 00:00:00 2001
From: Vincent Gao <gaobing1230@gmail.com>
Date: Tue, 23 Jun 2026 09:19:12 +0200
Subject: [PATCH 1/2] Recognize ``trace`` operations in docstrings

load_operations_from_docstring filters docstring keys against PATH_KEYS,
which omitted "trace". A trace: operation defined in a view docstring was
silently dropped, even though OpenAPI v3 (VALID_METHODS_OPENAPI_V3) and
the rest of apispec (e.g. resolve_refs_in_path) treat trace as a
first-class operation. Add "trace" to PATH_KEYS.
---
 src/apispec/yaml_utils.py |  2 +-
 tests/test_yaml_utils.py  | 18 ++++++++++++++++++
 2 files changed, 19 insertions(+), 1 deletion(-)

diff --git a/src/apispec/yaml_utils.py b/src/apispec/yaml_utils.py
index 52985dc5..6bc4c94b 100644
--- a/src/apispec/yaml_utils.py
+++ b/src/apispec/yaml_utils.py
@@ -36,7 +36,7 @@ def load_yaml_from_docstring(docstring: str) -> dict:
     return yaml.safe_load(yaml_string) or {}
 
 
-PATH_KEYS = {"get", "put", "post", "delete", "options", "head", "patch"}
+PATH_KEYS = {"get", "put", "post", "delete", "options", "head", "patch", "trace"}
 
 
 def load_operations_from_docstring(docstring: str) -> dict:
diff --git a/tests/test_yaml_utils.py b/tests/test_yaml_utils.py
index 6d7dd28c..2d22f266 100644
--- a/tests/test_yaml_utils.py
+++ b/tests/test_yaml_utils.py
@@ -29,6 +29,24 @@ def test_load_operations_from_docstring_empty_docstring(docstring):
     assert yaml_utils.load_operations_from_docstring(docstring) == {}
 
 
+def test_load_operations_from_docstring_trace():
+    def f():
+        """Foo.
+        ---
+        get:
+            responses:
+                200:
+                    description: ok
+        trace:
+            responses:
+                200:
+                    description: ok
+        """
+
+    operations = yaml_utils.load_operations_from_docstring(f.__doc__)
+    assert set(operations) == {"get", "trace"}
+
+
 def test_dict_to_yaml_unicode():
     assert yaml_utils.dict_to_yaml({"가": "나"}) == '"\\uAC00": "\\uB098"\n'
     assert yaml_utils.dict_to_yaml({"가": "나"}, {"allow_unicode": True}) == "가: 나\n"

From 72fb90c37e4cb94f67f22adc78dc1530e55a4460 Mon Sep 17 00:00:00 2001
From: Vincent Gao <gaobing1230@gmail.com>
Date: Tue, 23 Jun 2026 09:19:42 +0200
Subject: [PATCH 2/2] Add changelog entry for #1059

---
 CHANGELOG.rst | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/CHANGELOG.rst b/CHANGELOG.rst
index c47aded9..3aaf89e5 100644
--- a/CHANGELOG.rst
+++ b/CHANGELOG.rst
@@ -4,6 +4,11 @@ Changelog
 unreleased
 **********
 
+Bug fixes:
+
+- Recognize ``trace`` operations defined in view docstrings, instead of
+  silently dropping them (:pr:`1059`).
+
 Other changes:
 
 - Drop support for marshmallow 3, which is EOL.