Recognize trace operations in docstrings

[gaoflow]

Summary

load_operations_from_docstring filters the keys of a view docstring against PATH_KEYS, which omitted "trace":

PATH_KEYS = {"get", "put", "post", "delete", "options", "head", "patch"}

So a trace: operation defined in a docstring is silently dropped:

>>> from apispec.yaml_utils import load_operations_from_docstring
>>> doc = "Example.\n---\nget:\n    responses: {200: {description: ok}}\ntrace:\n    responses: {200: {description: ok}}\n"
>>> sorted(load_operations_from_docstring(doc))
['get']        # 'trace' is missing

This is inconsistent with the rest of apispec, which treats TRACE as a first-class OpenAPI v3 operation:

• core.py: VALID_METHODS_OPENAPI_V3 = VALID_METHODS_OPENAPI_V2 + ["trace"]
• core.py: resolve_refs_in_path iterates all eight methods, including trace

Only PATH_KEYS in yaml_utils.py was missed. The same docstring's get: operation is kept, confirming this is an oversight rather than intent.

Fix

Add "trace" to PATH_KEYS, mirroring VALID_METHODS_OPENAPI_V3.

Verification

• Reproduced on dev (41784ce): trace is dropped from load_operations_from_docstring (and end-to-end, absent from spec.to_dict()["paths"]); with the fix it is preserved.
• Added test_load_operations_from_docstring_trace; it fails before the fix and passes after.
• Full suite: 619 passed, 6 skipped (baseline 618 + the new test), no regressions. ruff check and ruff format --check clean.

---

This pull request was prepared with the assistance of AI, under my direction and review.

[lafrech]

Thanks for contributing.

Wondering if we should make this v3 only like VALID_METHODS. It might be difficult to implement and my stance in general is to be lax with this and assume users know what they are doing.

The non-reg test could be broadened to test all methods. Currently, tests pass if we remove options from the list. Maybe using a parametrized test.