Handle api-version parameter

[pshao25]

Background: We could have two kinds of api-version, in path or query, both are client parameters.

For path api-version, we define globally like

@server(
  "{Endpoint}/anomalydetector/{ApiVersion}",
  ".",
  {
    Endpoint: string,
    @path
    ApiVersion: APIVersion
  }
)

For query api-version, we currently have to define at each operation. But I have created https://github.com/microsoft/typespec/issues/2134, we might could define it globally.

Scenario 1: When there is no api-version defined in operation

@server(
  "{Endpoint}/anomalydetector",
  "Not path parameter",
  {
    Endpoint: string,
  }
)
@get op noAPIVersionParameter(): void; 

Our current behavior: generator will generate a client level api-version query parameter for each operation.

Per @timotheeguerin, this is injecting things which are not described in the spec and will prevent non azure SDK from working in the future.

Scenario 2: User defined api-version name

@post op create(@body pet: Pet, @query("my-apiverion") apiVersion: string): Pet | Error;

Current behavior:

public virtual Response Create(string apiVersion, RequestContent content, RequestContext context = null);
internal HttpMessage CreateCreateRequest(string apiVersion, RequestContent content, RequestContext context)
{
  uri.AppendQuery("my-apiverion", _apiVersion, true);
  uri.AppendQuery("api-version", _apiVersion, true);
}

Scenario 3: api-version is defined as a constant

@post op create(@body pet: Pet, @query apiVersion: "v1.2"): Pet | Error;

Current behavior:

internal HttpMessage CreateCreateRequest(RequestContent content, RequestContext context)
{
  uri.AppendQuery("apiVersion", "v1.2", true);
}

This apiVersion is independent from other operations. That means even I set apiversion in options as v1.1, for this specific operation, the apiversion is still v1.2.

[lirenhe]

@pshao25, do you have a real service that use scenario 2 and scenario 3?

[pshao25]

@pshao25, do you have a real service that use scenario 2 and scenario 3?

No, if we don't want to support them we need to reject these specs. Scenario 3 is in our test.