Add basic multi-version support to FR (#20693)

* Add basic multi-version support to FR

* enable multi-api testing with mostly 2.1p3

Co-authored-by: Mariana Rios Flores <[email protected]>

sdk/formrecognizer/Azure.AI.FormRecognizer/src/FormRecognizerClient.cs

@@ -58,7 +58,7 @@ public FormRecognizerClient(Uri endpoint, AzureKeyCredential credential, FormRec
 
             Diagnostics = new ClientDiagnostics(options);
             var pipeline = HttpPipelineBuilder.Build(options, new AzureKeyCredentialPolicy(credential, Constants.AuthorizationHeader));
-            ServiceClient = new FormRecognizerRestClient(Diagnostics, pipeline, endpoint.AbsoluteUri);
+            ServiceClient = new FormRecognizerRestClient(Diagnostics, pipeline, endpoint.AbsoluteUri, FormRecognizerClientOptions.GetVersionString(options.Version));
         }
 
         /// <summary>
@@ -93,7 +93,7 @@ public FormRecognizerClient(Uri endpoint, TokenCredential credential, FormRecogn
 
             Diagnostics = new ClientDiagnostics(options);
             var pipeline = HttpPipelineBuilder.Build(options, new BearerTokenAuthenticationPolicy(credential, Constants.DefaultCognitiveScope));
-            ServiceClient = new FormRecognizerRestClient(Diagnostics, pipeline, endpoint.AbsoluteUri);
+            ServiceClient = new FormRecognizerRestClient(Diagnostics, pipeline, endpoint.AbsoluteUri, FormRecognizerClientOptions.GetVersionString(options.Version));
         }
 
         /// <summary>

sdk/formrecognizer/Azure.AI.FormRecognizer/src/FormTrainingClient.cs

@@ -66,7 +66,7 @@ public FormTrainingClient(Uri endpoint, AzureKeyCredential credential, FormRecog
 
             Diagnostics = new ClientDiagnostics(options);
             HttpPipeline pipeline = HttpPipelineBuilder.Build(options, new AzureKeyCredentialPolicy(credential, Constants.AuthorizationHeader));
-            ServiceClient = new FormRecognizerRestClient(Diagnostics, pipeline, endpoint.AbsoluteUri);
+            ServiceClient = new FormRecognizerRestClient(Diagnostics, pipeline, endpoint.AbsoluteUri, FormRecognizerClientOptions.GetVersionString(options.Version));
         }
 
         /// <summary>
@@ -101,7 +101,7 @@ public FormTrainingClient(Uri endpoint, TokenCredential credential, FormRecogniz
 
             Diagnostics = new ClientDiagnostics(options);
             var pipeline = HttpPipelineBuilder.Build(options, new BearerTokenAuthenticationPolicy(credential, Constants.DefaultCognitiveScope));
-            ServiceClient = new FormRecognizerRestClient(Diagnostics, pipeline, endpoint.AbsoluteUri);
+            ServiceClient = new FormRecognizerRestClient(Diagnostics, pipeline, endpoint.AbsoluteUri, FormRecognizerClientOptions.GetVersionString(options.Version));
         }
 
         #region Training

sdk/formrecognizer/Azure.AI.FormRecognizer/src/autorest.md

@@ -11,6 +11,25 @@ require:
     - https://github.com/Azure/azure-rest-api-specs/blob/5a260d47021d8278c26dd6f946f4e6b97e0cd023/specification/cognitiveservices/data-plane/FormRecognizer/readme.md
 ```
 
+### Make the API version parameterized so we generate a multi-versioned API
+
+This should be fixed in the swagger, but we're working around it locally for now.
+``` yaml
+directive:
+- from: swagger-document
+  where: $["x-ms-parameterized-host"]
+  transform: >
+    $.hostTemplate = "{endpoint}/formrecognizer/{apiVersion}";
+    $.parameters.push({
+      "name": "apiVersion",
+      "description": "Form Recognizer API version (for example: v2.0).",
+      "x-ms-parameter-location": "client",
+      "required": true,
+      "type": "string",
+      "in": "path",
+      "x-ms-skip-url-encoding": true
+    });
+```
 
 ### Make AnalyzeResult.readResult optional
 This is a temporary work-around

sdk/formrecognizer/Azure.AI.FormRecognizer/tests/FormTrainingClient/FormTrainingClientLiveTests.cs

@@ -25,8 +25,8 @@ public class FormTrainingClientLiveTests : FormRecognizerLiveTestBase
         /// Initializes a new instance of the <see cref="FormTrainingClientLiveTests"/> class.
         /// </summary>
         /// <param name="isAsync">A flag used by the Azure Core Test Framework to differentiate between tests for asynchronous and synchronous methods.</param>
-        public FormTrainingClientLiveTests(bool isAsync)
-            : base(isAsync)
+        public FormTrainingClientLiveTests(bool isAsync, FormRecognizerClientOptions.ServiceVersion serviceVersion)
+            : base(isAsync, serviceVersion)
         {
         }
 
@@ -72,6 +72,7 @@ public async Task StartTraining(bool singlePage, bool labeled)
             CustomFormModel model = operation.Value;
 
             Assert.IsNotNull(model.ModelId);
+            Assert.IsNull(model.ModelName);
             Assert.IsNotNull(model.Properties);
             Assert.IsFalse(model.Properties.IsComposedModel);
             Assert.IsNotNull(model.TrainingStartedOn);
@@ -108,6 +109,7 @@ public async Task StartTraining(bool singlePage, bool labeled)
         [RecordedTest]
         [TestCase(true)]
         [TestCase(false)]
+        [ServiceVersion(Min = FormRecognizerClientOptions.ServiceVersion.V2_1_Preview_3)]
         public async Task CheckFormTypeinSubmodelAndRecognizedForm(bool labeled)
         {
             var client = CreateFormTrainingClient();
@@ -135,6 +137,7 @@ public async Task CheckFormTypeinSubmodelAndRecognizedForm(bool labeled)
         [RecordedTest]
         [TestCase(false)]
         [TestCase(true)]
+        [ServiceVersion(Min = FormRecognizerClientOptions.ServiceVersion.V2_1_Preview_3)]
         public async Task StartCreateComposedModel(bool useTokenCredential)
         {
             var client = CreateFormTrainingClient(useTokenCredential);
@@ -203,6 +206,7 @@ public async Task StartCreateComposedModel(bool useTokenCredential)
         }
 
         [RecordedTest]
+        [ServiceVersion(Min = FormRecognizerClientOptions.ServiceVersion.V2_1_Preview_3)]
         public async Task StartCreateComposedModelFailsWithInvalidId()
         {
             var client = CreateFormTrainingClient();
@@ -245,6 +249,7 @@ public async Task StartTrainingFailsWithInvalidPrefix()
         }
 
         [RecordedTest]
+        [ServiceVersion(Min = FormRecognizerClientOptions.ServiceVersion.V2_1_Preview_3)]
         public async Task StartTrainingWithLabelsModelName()
         {
             var client = CreateFormTrainingClient();
@@ -260,6 +265,7 @@ public async Task StartTrainingWithLabelsModelName()
         }
 
         [RecordedTest]
+        [ServiceVersion(Min = FormRecognizerClientOptions.ServiceVersion.V2_1_Preview_3)]
         public async Task StartTrainingWithNoLabelsModelName()
         {
             var client = CreateFormTrainingClient();
@@ -401,6 +407,7 @@ public async Task CopyModel(bool useTokenCredential)
         }
 
         [RecordedTest]
+        [ServiceVersion(Min = FormRecognizerClientOptions.ServiceVersion.V2_1_Preview_3)]
         public async Task CopyModelWithLabelsAndModelName()
         {
             var sourceClient = CreateFormTrainingClient();
@@ -431,6 +438,7 @@ public async Task CopyModelWithLabelsAndModelName()
         [RecordedTest]
         [TestCase(true)]
         [TestCase(false)]
+        [ServiceVersion(Min = FormRecognizerClientOptions.ServiceVersion.V2_1_Preview_3)]
         public async Task CopyComposedModel(bool useTokenCredential)
         {
             var sourceClient = CreateFormTrainingClient(useTokenCredential);
@@ -468,6 +476,7 @@ public async Task CopyComposedModel(bool useTokenCredential)
         }
 
         [RecordedTest]
+        [ServiceVersion(Min = FormRecognizerClientOptions.ServiceVersion.V2_1_Preview_3)]
         public async Task CopyModelWithoutLabelsAndModelName()
         {
             var sourceClient = CreateFormTrainingClient();

sdk/formrecognizer/Azure.AI.FormRecognizer/tests/Infrastructure/FormRecognizerLiveTestBase.cs

@@ -9,11 +9,21 @@
 
 namespace Azure.AI.FormRecognizer.Tests
 {
+    [ClientTestFixture(
+    FormRecognizerClientOptions.ServiceVersion.V2_0,
+    FormRecognizerClientOptions.ServiceVersion.V2_1_Preview_3)]
     public class FormRecognizerLiveTestBase : RecordedTestBase<FormRecognizerTestEnvironment>
     {
-        public FormRecognizerLiveTestBase(bool isAsync)
+        /// <summary>
+        /// The version of the REST API to test against.  This will be passed
+        /// to the .ctor via ClientTestFixture's values.
+        /// </summary>
+        private readonly FormRecognizerClientOptions.ServiceVersion _serviceVersion;
+
+        public FormRecognizerLiveTestBase(bool isAsync, FormRecognizerClientOptions.ServiceVersion serviceVersion)
             : base(isAsync)
         {
+            _serviceVersion = serviceVersion;
             Sanitizer = new FormRecognizerRecordedTestSanitizer();
         }
 
@@ -39,7 +49,7 @@ public FormRecognizerLiveTestBase(bool isAsync)
         protected FormRecognizerClient CreateFormRecognizerClient(out FormRecognizerClient nonInstrumentedClient, bool useTokenCredential = false, string apiKey = default)
         {
             var endpoint = new Uri(TestEnvironment.Endpoint);
-            var options = InstrumentClientOptions(new FormRecognizerClientOptions());
+            var options = InstrumentClientOptions(new FormRecognizerClientOptions(_serviceVersion));
 
             if (useTokenCredential)
             {
@@ -77,7 +87,7 @@ protected FormRecognizerClient CreateFormRecognizerClient(out FormRecognizerClie
         protected FormTrainingClient CreateFormTrainingClient(out FormTrainingClient nonInstrumentedClient, bool useTokenCredential = false, string apiKey = default)
         {
             var endpoint = new Uri(TestEnvironment.Endpoint);
-            var options = InstrumentClientOptions(new FormRecognizerClientOptions());
+            var options = InstrumentClientOptions(new FormRecognizerClientOptions(_serviceVersion));
 
             if (useTokenCredential)
             {

sdk/formrecognizer/Azure.AI.FormRecognizer/tests/Models/OperationsLiveTests.cs

@@ -24,8 +24,8 @@ public class OperationsLiveTests : FormRecognizerLiveTestBase
         /// Initializes a new instance of the <see cref="OperationsLiveTests"/> class.
         /// </summary>
         /// <param name="isAsync">A flag used by the Azure Core Test Framework to differentiate between tests for asynchronous and synchronous methods.</param>
-        public OperationsLiveTests(bool isAsync)
-            : base(isAsync)
+        public OperationsLiveTests(bool isAsync, FormRecognizerClientOptions.ServiceVersion serviceVersion)
+            : base(isAsync, serviceVersion)
         {
         }
 
@@ -60,6 +60,7 @@ public async Task RecognizeReceiptsOperationCanPollFromNewObject()
         }
 
         [RecordedTest]
+        [ServiceVersion(Min = FormRecognizerClientOptions.ServiceVersion.V2_1_Preview_3)]
         public async Task RecognizeInvoicesOperationCanPollFromNewObject()
         {
             var client = CreateFormRecognizerClient(out var nonInstrumentedClient);
@@ -75,6 +76,7 @@ public async Task RecognizeInvoicesOperationCanPollFromNewObject()
         }
 
         [RecordedTest]
+        [ServiceVersion(Min = FormRecognizerClientOptions.ServiceVersion.V2_1_Preview_3)]
         public async Task RecognizeIdDocumentsOperationCanPollFromNewObject()
         {
             var client = CreateFormRecognizerClient(out var nonInstrumentedClient);
@@ -126,6 +128,7 @@ public async Task TrainingOperationCanPollFromNewObject()
         }
 
         [RecordedTest]
+        [ServiceVersion(Min = FormRecognizerClientOptions.ServiceVersion.V2_1_Preview_3)]
         public async Task CreateComposedModelOperationCanPollFromNewObject()
         {
             var client = CreateFormTrainingClient(out var nonInstrumentedClient);