[Discussion] How best to customize "body" parameter name for BodyParameter

[weidongxu-microsoft]

Context

Isabella added BodyParameter to service spec.

alias BodyParameter<
  T,
  TName extends valueof string = "body",
  TDoc extends valueof string = "Body parameter."
> = {
  @doc(TDoc)
  @friendlyName(TName)
  @bodyRoot
  body: T;
};

The default parameter name is body.

In certain cases, client would like either to revert it back to name prior to this change, to avoid breaking changes; or use a different name for specific language.

Therefore, the question is how best to do this

1. for a single API
2. for a single (or a subset of) language

Approaches considered

For all APIs

If BodyParameter is a model (instead of alias), this would be easiest

@@clientName(BodyParameter.body, "requestOptions");

For all languages

This would be easiest

op getEmbeddings is Azure.Core.ResourceAction<
  Deployment,
  BodyParameter<EmbeddingsOptions, "embeddingOptions", "<doc>">,
  Embeddings
>;

For 1 API and specified language

Use meta type op.parameters::<parameter>

Chenjie mentioned about op.parameters::body.

It works for simple API (if BodyParameter is a model) e.g.

op simpleApi(...BodyParameter<EmbeddingsOptions>): Embeddings;

@@clientName(simpleApi::parameters.body, "embeddingOptions");

But it does not work for templated API e.g.

op getEmbeddings is Azure.Core.ResourceAction<
  Deployment,
  BodyParameter<EmbeddingsOptions>,
  Embeddings
>;

@@clientName(getEmbeddings::parameters.body, "embeddingOptions");

playground

We may check with Timothee whether this is a bug.

Just write a model with @bodyRoot for the API

This would be cumbersome, but it should work

model EmbeddingsBodyParameter {
  @doc("<doc>")
  @bodyRoot
  body: EmbeddingsOptions;
}

@@clientName(EmbeddingsBodyParameter.body, "embeddingOptions");