multiple API versions

[cataggar]

I made the assumption that each Tag in a spec readme would be for a unique version. I'm not sure that is true. I'm beginning to think that it is not.

Using specification\applicationinsights\resource-manager\readme.md as an example since I was looking into Azure/azure-rest-api-specs#17215. It defines this Tag:

### Tag: package-2020-02-02

These settings apply only when `--tag=package-2020-02-02` is specified on the command line.

``` yaml $(tag) == 'package-2020-02-02'
input-file:
- Microsoft.Insights/stable/2015-05-01/aiOperations_API.json
- Microsoft.Insights/stable/2015-05-01/componentAnnotations_API.json
- Microsoft.Insights/stable/2015-05-01/componentApiKeys_API.json
- Microsoft.Insights/stable/2015-05-01/componentContinuousExport_API.json
- Microsoft.Insights/stable/2015-05-01/componentFeaturesAndPricing_API.json
- Microsoft.Insights/stable/2015-05-01/componentProactiveDetection_API.json
- Microsoft.Insights/stable/2015-05-01/componentWorkItemConfigs_API.json
- Microsoft.Insights/stable/2015-05-01/favorites_API.json
- Microsoft.Insights/stable/2015-05-01/webTestLocations_API.json
- Microsoft.Insights/stable/2015-05-01/webTests_API.json
- Microsoft.Insights/stable/2015-05-01/analyticsItems_API.json
- Microsoft.Insights/stable/2015-05-01/workbooks_API.json
- Microsoft.Insights/stable/2015-05-01/myworkbooks_API.json
- Microsoft.Insights/stable/2020-02-02/components_API.json
```.

AutoRust picks 2020-02-02 as the API from the `components_API.json file.

azure-sdk-for-rust/services/mgmt/applicationinsights/src/package_2020_02_02/mod.rs

Line 4 in c10d00a

pub const API_VERSION: &str = "2020-02-02";

From this code:

azure-sdk-for-rust/services/autorust/codegen/src/spec.rs

Lines 110 to 120 in c10d00a

	/// Look for specs with operations and return the last one sorted alphabetically
	pub fn api_version(&self) -> Option<String> {
	let mut versions: Vec<&str> = self
	.docs()
	.values()
	.filter(|doc| !doc.paths().is_empty())
	.filter_map(|api| api.info.version.as_deref())
	.collect();
	versions.sort_unstable();
	versions.last().map(|version| version.to_string())
	}

The assumption was that all of the operations would be available in that new API and define the tag like this show that you are just introducing new operations in the components_API.json, but nothing else is changing. I'm doubting this is true.

If it isn't true, isn't it weird to have an SDK generated from a tag that is using two different API versions? If you look at the latest Tag, it is mixing 7 different API versions and 3 of them are marked preview.

### Tag: package-2021-11-01

These settings apply only when `--tag=package-2021-11-01` is specified on the command line.

``` yaml $(tag) == 'package-2021-11-01'
input-file:
  - Microsoft.Insights/stable/2015-05-01/aiOperations_API.json
  - Microsoft.Insights/stable/2015-05-01/componentAnnotations_API.json
  - Microsoft.Insights/stable/2015-05-01/componentApiKeys_API.json
  - Microsoft.Insights/stable/2015-05-01/componentContinuousExport_API.json
  - Microsoft.Insights/stable/2015-05-01/componentFeaturesAndPricing_API.json
  - Microsoft.Insights/stable/2015-05-01/componentProactiveDetection_API.json
  - Microsoft.Insights/stable/2015-05-01/componentWorkItemConfigs_API.json
  - Microsoft.Insights/stable/2015-05-01/favorites_API.json
  - Microsoft.Insights/stable/2015-05-01/webTestLocations_API.json
  - Microsoft.Insights/stable/2015-05-01/webTests_API.json
  - Microsoft.Insights/stable/2015-05-01/analyticsItems_API.json
  - Microsoft.Insights/stable/2020-11-20/workbookTemplates_API.json
  - Microsoft.Insights/stable/2021-03-08/myworkbooks_API.json
  - Microsoft.Insights/stable/2021-08-01/workbooks_API.json
  - Microsoft.Insights/preview/2018-05-01-preview/components_API.json
  - Microsoft.Insights/preview/2020-03-01-preview/componentLinkedStorageAccounts_API.json
  - Microsoft.Insights/preview/2020-06-02-preview/livetoken_API.json
```.

I don't understand why this is being done this way. I'll try to gather some more examples.

[cataggar]

For analysis, here are all input files for every tag:
https://gist.github.com/cataggar/86a632928f3433d933bd444098d36a0f

[heaths]

They shouldn't be doing that. OpenAPI Hub creates a complete copy to avoid cases where someone makes an update to in-development api-versions and inadvertently breaks compat with older versions. @mikekistler should we log a bug against Insights for doing that and even explicitly call out not doing that?

For a large number of services and service versions I've reviewed, I've never seen this. Hopefully it's not too prevalent.

[mikekistler]

I think we should clearly document what is allowed/recommended, and to my knowledge we currently do not.

We could certainly open an issue asking them to change it, but without clear guidance I don't think we could call it a "bug".

[heaths]

Should we bring this up at the next REST API meeting? From my experience, oversharing swaggers like this leads to eventual problems. I've seen it both for Key Vault / Managed HSM and Cognitive Language pillar services (the latter has already stopped sharing, and we're exploring the latter).

[mikekistler]

I've added this to the agenda for the next REST API Stewardship meeting.