docs: improve migration guidance for request body parameter naming (Swagger → TypeSpec)

[Copilot]

The breakingchange.md FAQ lacked guidance on when and why to rename request body parameters during Swagger migration, causing inconsistent migration decisions.

Changes to Customizing Request Payload Parameter Names

• Breaking change callout: Explicitly states that request body parameter names affect SDK method signatures and renaming them is a client-visible breaking change.
• Migration decision guidance: New subsection with clear fork:
  • Preserve Swagger named body parameters (via @@clientName) when SDK backward compatibility is required
  • Use standardized TypeSpec names only when a breaking change is planned or the SDK surface is new
• Concrete migration example: One minimal example showing how to preserve the original Swagger parameter name for a createOrUpdate PUT operation:

// In your client.tsp - preserve the original Swagger parameter name to avoid a breaking change
@@clientName(Widgets.createOrUpdate::parameters.resource, "widget");

• Keyword alignment: Section now explicitly surfaces "Swagger named body parameters", "avoid breaking changes", "SDK compatibility", "standardized request body names", and "migration decision" for discoverability (including by AI assistants).

Original prompt

---

This section details on the original issue you should resolve

<issue_title>Improve migration guidance for request body parameter naming from Swagger to TypeSpec</issue_title>
<issue_description>## Problem

The documentation page
Customizing Request Payload Parameter Names explains how to rename request body parameters using @@clientName, but does not explain when or why this should be done.

As a result, Teams chatbot cannot answer common migration questions such as:

“When converting from existing Swagger with named body parameters, should we keep the original parameter names to avoid a breaking change, or use standardized TypeSpec names and document the breaking change?”

This causes repeated human clarification and inconsistent migration decisions.

Actions:

1. Add explicit decision guidance
   Clearly state:

Preserving existing names is recommended when SDK backward compatibility is required, because renaming request body parameters is a breaking change.
Using standardized TypeSpec names is acceptable only when:

a breaking change is already planned, or
the SDK surface is new.

2. Explicitly link parameter renaming to breaking changes
   Add a paragraph stating that:

Request body parameter names affect generated SDK method signatures.
Changing them constitutes a client-visible breaking change.

3. Add a minimal migration example
   Select one scenario and add one case, don't update all methods which make this doc complex.

4. Improve keyword alignment
   Ensure the doc explicitly includes:

“Swagger named body parameters”
“avoid breaking changes”
“SDK compatibility”
“standardized request body names”
“migration decision”

Note: Modify this document only: https://azure.github.io/typespec-azure/docs/migrate-swagger/faq/breakingchange/ and focus on the session of #customizing-request-payload-parameter-names
All format tool should pass.

</issue_description>

Comments on the Issue (you are @copilot in this section)

• Fixes Improve migration guidance for request body parameter naming from Swagger to TypeSpec #4079

---

🔒 GitHub Advanced Security automatically protects Copilot coding agent pull requests. You can protect all pull requests by enabling Advanced Security for your repositories. Learn more about Advanced Security.

[timotheeguerin]

isn't exactly what each section below shows?