OpenAPI and Autorest emitters need updating for shared routes

[tjprescott]

Issue #1133 enables having multiple operations decorated with @route using the {shared: true} option on the decorator. The autorest and openAPI emitters should be updated to make use of this feature, as appropriate.

Design issue: #984. However, this did not actually clarify how Autorest and OpenAPI3 emitters should be updated for these scenarios.

[markcowl]

est: 8

[tjprescott]

Some scenarios we want to support. Thanks to @johanste for coming up providing these (see Playground):

1 - Shared Route with Return Type Disambiguation Through Content Header (content negotiation)

Related issue: https://github.com/Azure/cadl-azure/issues/2438

@route("/getCertificate", {shared: true})
@get op getPemFile(@header accept?: "application/x-pem-file"): PemFile;

@route("/getCertificate", {shared: true})
@get op getPkcs7File(@header accept?: "application/pkcs7-mime"): Pkcs7File;

2 - Shared Route with Disambiguation Through Query Param

/*
  Broken - only one of the query parameters shows up in openapi emitters.
  Both should show up marked as optional.
*/
@route("/sharedroutes/resources", { shared: true})
op listByResourceGroup(... Resource, @query resourceGroup: string): Resource[];

@route("/sharedroutes/resources", { shared: true})
op listBySubscription(... Resource, @query subscription: string): Resource[];

3 - Overload with Disambiguation Through Query Param

@route("/overloads/resources")
op listResources(... Resource, @query group?: string, @query subscription?: string): Resource[];

@overload(listResources)
op listByResourceGroup(... Resource, @query resourceGroup: string): Resource[];

@overload(listResources)
op listBySubscription(... Resource, @query subscription: string): Resource[];

4 - Overloading Different Routes (Not sure we actually want to support this...)

/*
  Chances are that this is more of a client side-car method scenario in which
  case overloads wouldn't be involved, but rather multiple <op something is list...>

  Currently broken - includes the route-less "root" method. But see above.
*/
op listResources(... Resource, @query group?: string, @query subscription?: string): Resource[];

@route("/overloaddifferentroutes/resourceGroups/{resourceGroup}/resources")
@overload(listResources)
op listByResourceGroup(... Resource, resourceGroup: string): Resource[];

@route("/overloaddifferentroutes/subscriptions/{subscription}/resources")
@overload(listResources)
op listBySubscription(... Resource, subscription: string): Resource[];

[johanste]

For swagger/autorest, in order to produce good libraries using autorest, we needed to use x-ms-paths whenever the input parameter combination deterministically determined the return type. Similarly, we needed to use it whenever parameters were mutually exclusive.

I would say that the easiest thing to do is to use x-ms-paths whenever it is easiest for OA2 unless we are already doing the work to disambiguate for OA3 in a way that is OA2 compatible.

E.g. any solution that uses anyOf/oneOf or per-content-type responses to solve the problem for OA3 are not OA2 compatible, and thus we can't use them and would fall back to x-ms-paths for OA2.

Doing extra work to produce less precise specs for OA2 to avoid confusing tools that we are not going to use feel like not well-spent time.