[Azure Search] Add Get Documents API (a.k.a. Lookup) to data plane AP…

…I spec (#5169)

* [Azure Search] Add Get Documents (a.k.a. Lookup) API to data plane spec

Note that this API already exists in the .NET SDK, but is currently
implemented as custom code. We need to add transform directives for the
generated code because otherwise there's no way to pass custom
JsonSerializerSettings into the generated code (which is a requirement for
our data plane).

Also renamed some example files to be more consistent with existing naming
conventions.

* [Azure Search] Fixing a few Swagger validation errors

* [Azure Search] Fixing another validation error

specification/search/data-plane/Microsoft.Azure.Search.Data/preview/2017-11-11-preview/examples/SearchIndexPostAutocomplete.json → specification/search/data-plane/Microsoft.Azure.Search.Data/preview/2017-11-11-preview/examples/SearchIndexAutocompleteDocumentsPost.json

@@ -11,7 +11,7 @@
           "highlightPostTag": "</em>",
           "highlightPreTag": "<em>",
           "minimumCoverage": 80,
-          "searchFields": ["title", "description"],
+          "searchFields": "title,description",
           "top": 10
         }
     },

specification/search/data-plane/Microsoft.Azure.Search.Data/preview/2017-11-11-preview/examples/SearchIndexGetDocument.json

@@ -0,0 +1,19 @@
+{
+   "parameters": {
+      "searchServiceName": "myservice",
+      "searchDnsSuffix": "search.windows.net",
+      "indexName": "myindex",
+      "api-version": "2017-11-11-Preview",
+      "key": "1",
+      "$select": ["docId", "title", "description"]
+   },
+   "responses": {
+      "200": {
+         "body": {
+            "description": "Cheapest hotel in town",
+            "docId": "1",
+            "title": "Nice Hotel"
+         }
+      }
+   }
+}

specification/search/data-plane/Microsoft.Azure.Search.Data/preview/2017-11-11-preview/searchindex.json

@@ -64,6 +64,54 @@
         }
       }
     },
+    "/docs('{key}')": {
+      "get": {
+        "tags": [
+          "Documents"
+        ],
+        "operationId": "Documents_Get",        
+        "externalDocs": {
+          "url": "https://docs.microsoft.com/rest/api/searchservice/lookup-document"
+        },
+        "x-ms-examples": {
+          "SearchIndexGetDocument": { "$ref": "./examples/SearchIndexGetDocument.json" }
+        },
+        "description": "Retrieves a document from the Azure Search index.",
+        "parameters": [
+          {
+            "name": "key",
+            "in": "path",
+            "required": true,
+            "description": "The key of the document to retrieve.",
+            "type": "string"
+          },
+          {
+            "name":"$select",
+            "in": "query",
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "List of field names to retrieve for the document; Any field not retrieved will be missing from the returned document.",
+            "x-ms-client-name": "SelectedFields"
+          },
+          {
+            "$ref": "#/parameters/ApiVersionParameter"
+          },
+          {
+            "$ref": "#/parameters/ClientRequestIdParameter"
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "",
+            "schema": {
+              "type": "object"
+            }
+          }
+        }
+      }
+    },
     "/docs/autocomplete": {
       "get": {
         "tags": [
@@ -74,7 +122,7 @@
           "url": "https://docs.microsoft.com/rest/api/searchservice/autocomplete"
         },
         "x-ms-examples": {
-          "SearchIndexGetAutocomplete": { "$ref": "./examples/SearchIndexGetAutocomplete.json" }
+          "SearchIndexAutocompleteDocumentsGet": { "$ref": "./examples/SearchIndexAutocompleteDocumentsGet.json" }
         },
         "description": "Autocompletes incomplete query terms based on input text and matching terms in the Azure Search index.",
         "parameters": [
@@ -198,7 +246,7 @@
           "url": "https://docs.microsoft.com/rest/api/searchservice/autocomplete"
         },
         "x-ms-examples": {
-          "SearchIndexPostAutocomplete": { "$ref": "./examples/SearchIndexPostAutocomplete.json" }
+          "SearchIndexAutocompleteDocumentsPost": { "$ref": "./examples/SearchIndexAutocompleteDocumentsPost.json" }
         },
         "description": "Autocompletes incomplete query terms based on input text and matching terms in the Azure Search index.",
         "parameters": [
@@ -209,7 +257,7 @@
             "$ref": "#/parameters/ApiVersionParameter"
           },
           {
-            "name": "AutocompleteRequest",
+            "name": "autocompleteRequest",
             "in": "body",
             "required": true,
             "schema": {

specification/search/data-plane/Microsoft.Azure.Search.Data/readme.md

@@ -124,9 +124,30 @@ directive:
   - from: source-file-csharp
     where: $
     transform: >-
-      return $.replace( /DocumentsOperations/g, "DocumentsProxyOperations" ).
+      return $.
+        replace( /DocumentsOperations/g, "DocumentsProxyOperations" ).
         replace( /public (partial interface IDocumentsProxyOperations)/g, "internal $1" ).
-        replace( /public virtual IDocumentsProxyOperations Documents ({ get;)/g, "internal IDocumentsProxyOperations DocumentsProxy $1" ).
+        replace( /public virtual (IDocumentsProxyOperations) Documents ({ get;)/g, "internal $1 DocumentsProxy $2" ).
         replace( /Documents = new DocumentsProxyOperations\(this\);/g, "DocumentsProxy = new DocumentsProxyOperations\(this\);" ).
         replace( /(Gets the) IDocumentsProxyOperations(.\s*\n\s*\/\/\/ <\/summary>\s*\n\s*)IDocumentsProxyOperations (Documents { get; })/g, "$1 IDocumentsOperations$2IDocumentsOperations $3" )
+####
+  # Adds extra JsonSerializerSettings parameters to all operation methods. This enables the SDK to delegate serialization/de-serialization to the custom serializer on a per-call basis.
+  - from: source-file-csharp
+    where: $
+    transform: >-
+      return $.
+        replace( /(Async\(.*, CancellationToken cancellationToken = default\(CancellationToken\))/g, "$1, Newtonsoft.Json.JsonSerializerSettings requestSerializerSettings = null, Newtonsoft.Json.JsonSerializerSettings responseDeserializerSettings = null" ).
+        replace( /(DeserializeObject<.+>\(.+), Client\.DeserializationSettings/g, "$1, responseDeserializerSettings ?? Client.DeserializationSettings" ).
+        replace( /(SerializeObject\(.+), Client\.SerializationSettings/g , "$1, requestSerializerSettings ?? Client.SerializationSettings" )
+####
+  # Make GetWithHttpMessagesAsync generic so we can tell the deserializer what type to instantiate.
+  # ASSUMPTION: Only GetWithHttpMessagesAsync makes a call to DeserializeObject<object>(), and only when it's deserializing the non-error response.
+  # Ideally we'd be able to more finely target these transform rules.
+  - from: source-file-csharp
+    where: $
+    transform: >-
+      return $.
+        replace( /(Task<AzureOperationResponse)<object>(> GetWithHttpMessagesAsync)/g, "$1<T>$2<T>" ).
+        replace( /(DeserializeObject)<object>/g, "$1<T>" ).
+        replace( /(var _result = new AzureOperationResponse)<object>/g, "$1<T>" )
 ```