Document standard $top/$skip parameters for ARM subscription list operations

[Copilot]

ARM docs described the reusable pagination parameter models, but did not show how to apply them to ArmListBySubscription via the Parameters template argument. This left a common authoring path undocumented and encouraged hand-rolled query models.

• What changed

  • Added focused guidance to the ARM resource operations how-to for subscription-scoped list operations.
  • Documented the canonical pattern for wiring standard pagination parameters through Parameters instead of defining raw @query("$top") / @query("$skip") properties.

• Documented parameter options

  • ARM-native reusable parameters:
    • ArmTopParameter & ArmSkipParameter
  • Azure Core reusable list model:
    • Azure.Core.StandardListQueryParameters

• Example

  @armResourceOperations
  interface Employees {
    listBySubscription is ArmListBySubscription<
      Employee,
      Parameters = ArmTopParameter & ArmSkipParameter
    >;
  }

  @armResourceOperations
  interface Employees {
    listBySubscription is ArmListBySubscription<
      Employee,
      Parameters = Azure.Core.StandardListQueryParameters
    >;
  }

[markcowl]

These don't actually inject the $top and $skip` names, so it's preferred these are not used for ARM.

: https://github.com/Azure/typespec-azure/blob/main/packages/typespec-azure-core/lib/models.tsp#L62-L74

[haolingdong-msft]

Thanks Mark for the comment.I saw the code of Azure.Core.StandardListQueryParameters has $top and $skip parameters. https://github.com/Azure/typespec-azure/blob/main/packages/typespec-azure-core/lib/models.tsp#L120-L124
Do I misunderstand anything?

@doc("Provides the most common query parameters for list operations.")
model StandardListQueryParameters {
  ...TopQueryParameter;
  ...SkipQueryParameter;
  ...MaxPageSizeQueryParameter;
}

[haolingdong-msft]

I also noticed there are a few other standard query parameters already defined in the code. Do you have any thoughts on how we should guide users to use them?
https://github.com/Azure/typespec-azure/blob/main/packages/typespec-azure-core/lib/models.tsp#L93-L117

I’m wondering if we should include all of the standard query parameters, or maybe just highlight the most common ones. Curious what you think here.

[markcowl]

Note that there is also a standard $filter parameter we should mention: https://azure.github.io/typespec-azure/docs/libraries/azure-resource-manager/reference/data-types/#Azure.ResourceManager.ArmFilterParameter