Add support for alternate keys in code indexers

[baywet]

Notes from a conversation between myself and @baywet

The current OpenAPI specification says that the following is invalid

  /pets/{petId}/fur
  /pets/{name}/hair

However, I expect future iterations of the specification will relax this constraint and we know that these already exist in the wild. The notion of a collection of things having multiple candidate keys is a common concept and we should be able to model this.

We currently model these parameter segments as a CodeIndexer DOM model. Currently the CodeIndexer doesn't support the notion of alternate keys. We think it is worth exploring adding support for alternate keys to the CodeIndexer. We can continue to use the first parameter alphabetically as the default primary key, and all other parameters as alternate keys. This allows us to introduce support for a x-primary-key hint in the OpenAPI description that enables a particular path to be stable in its use of syntax like the C# indexer.

It may be possible that different candidate keys return different types. From a logical perspective the different types should be closely related, but from code perspective the types could be different. This does warp the concept of CodeIndexer slightly, but may be tolerable.

Adding this notion of candidate/alternate keys to the code indexer would remove the need for merging of nodes and the language refiners can emit specific named indexer methods for alternate keys and some default indexer method for the primary key, or they can emit specific named indexer methods for all the candidate keys.

Originally posted by @darrelmiller in #4174 (comment)

[baywet]

Cleanup instructions;

• remove this method and associated
• repurpose these tests and below
• update the second line of this integration test to look something like client.repos().byTemplateRepoOwner("foo").byTemplateRepoId("bar").generate().get()

[andrueastman]

Cleanup instructions;

• remove this method and associated
• repurpose these tests and below
• update the second line of this integration test to look something like client.repos().byTemplateRepoOwner("foo").byTemplateRepoId("bar").generate().get()

To add we should also

• Unsuppress tests at Cleanup integration tests #4263 for the apisguru::github.com:api.github.com endpoint.