[yeongseon]

Summary

Document the compatibility plan for moving protected Swagger UI requests from query-string keys to header forwarding.

Changes

• Describe affected use cases in docs/security.md and align docs/api.md and README.md.
• Propose retaining query as the default in the first release with a deprecation warning, then switching to header no earlier than the following minor release and before 1.0.
• Keep explicit query mode available during the transition; the release boundary remains a maintainer decision.

Validation

• Documentation-only change; no runtime behavior changed.
• Existing tests cover header forwarding, URL cleanup, same-origin restrictions, and redirect handling (tests/test_swagger_ui_key_forwarding.py, tests/test_docs_key_forwarding.py, tests/test_docs_key_browser.py). These tests were not reported as rerun for this PR.

Related Issues

Closes #830

[Copilot]

🟡 Changes recommended

The edge-authentication guidance needs qualification to avoid disabling forwarding when Functions authentication still requires a key.

1 open issue

• Avoid removing Functions key forwarding when routes still require keys · New

What changed in this PR

This documentation-only PR defines the compatibility boundary for switching protected Swagger UI registrations from implicit query-key forwarding to header forwarding. Runtime behavior is unchanged.

Changes:

• Documents affected consumers and explicit forwarding options.
• Keeps the warning’s first release on the legacy default, with the switch deferred to a later pre-1.0 minor.
• Preserves explicit "query" support and links the README and API reference to the migration guidance.

File	Description
README.md	Links the default-change timeline to the security guide.
docs/​security.md	Adds affected-consumer guidance and the compatibility boundary.
docs/​api.md	Aligns the API reference with the migration timeline.

_{Review effort: Balanced}