[Azure Search] Add Search API to data plane Swagger spec (#5315)

* [Azure Search] Updating some Swagger descriptions to be more doc-friendly

Sometimes we over-describe things, especially "comma-separated lists" in
query string parameters. These are modeled as arrays in Swagger, which are
already understood to be comma-separated lists. They are modeled as
collections in generated code, so they are decidedly not comma-separated
lists in that context. So removing this phrase is a win-win.

* [Azure Search] Adding some missing readOnly attributes

* Adding Search API to the Azure Search data plane spec

* [Azure Search] Use regexes to generate code for server-side paging

This change introduces some very hacky regexes to customize the generated
code for server-side paging of the GET and POST Search APIs. They work by
splitting the generated SearchGet and SearchPost operations in two, so that
the portion that operates on a URL and request body can be reused.

This workaround is necessary because AutoRest lacks flexibility around
paging. The current x-ms-pageable implementation doesn't work for us because
it doesn't model additional top-level response properties or continuation
POST requests (only nextLink/GET).

The only other alternative to this approach besides custom code would have
been to try to parse the nextLink URL query string to reconstitute parameters
to pass to the generated SearchGet and SearchPost operations. This is
unacceptable for Azure Search, since it would exclude custom parameters that
can't be modeled in Swagger, like personalization IDs for custom ranking.
Neither AutoRest nor apparently Open API support modeling arbitrary query
string parameters.

Ideally we'll find a pattern common to other data plane APIs so we don't have
to hack this with regexes for every target language, but it's good enough for
now.

* [Azure Search] Rename some client properties for consistency

* [Azure Search] Make AutocompleteMode non-nullable

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

@@ -0,0 +1,65 @@
+{
+   "parameters": {
+      "searchServiceName": "myservice",
+      "searchDnsSuffix": "search.windows.net",
+      "indexName": "myindex",
+      "api-version": "2017-11-11-Preview",
+      "$count": true,
+      "facet": [ "category,count:10,sort:count" ],
+      "$filter": "rating gt 10",
+      "highlight": [ "title" ],
+      "highlightPostTag": "</em>",
+      "highlightPreTag": "<em>",
+      "minimumCoverage": 80,
+      "$orderby": [ "search.score() desc", "rating desc" ],
+      "queryType": "simple",
+      "scoringParameters": [ "currentLocation--122.123,44.77233" ],
+      "scoringProfile": "sp",
+      "search": "nice hotels",
+      "searchFields": [ "title", "description" ],
+      "searchMode": "any",
+      "$select": [ "docId", "title", "description" ],
+      "$skip": 100,
+      "$top": 10
+   },
+   "responses": {
+      "200": {
+         "body": {
+            "@odata.count": 25,
+            "@search.coverage": 80,
+            "@search.facets": {
+               "category": [
+                  {
+                     "count": 1,
+                     "value": "Economy"
+                  },
+                  {
+                     "count": 1,
+                     "value": "Luxury"
+                  }
+               ]
+            },
+            "value": [
+               {
+                  "@search.score": 1.50,
+                  "@search.highlights": {
+                     "title": [ "<em>Nice</em> <em>Hotel</em>" ]
+                  },
+                  "description": "Cheapest hotel in town",
+                  "docId": "1",
+                  "title": "Nice Hotel"
+               },
+               {
+                  "@search.score": 0.70,
+                  "@search.highlights": {
+                     "title": [ "Fancy <em>Hotel</em>" ]
+                  },
+                  "description": "Best hotel in town",
+                  "docId": "2",
+                  "title": "Fancy Hotel"
+               }
+            ]
+         }
+      }
+   }
+}

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

@@ -0,0 +1,86 @@
+{
+   "parameters": {
+      "searchServiceName": "myservice",
+      "searchDnsSuffix": "search.windows.net",
+      "indexName": "myindex",
+      "api-version": "2017-11-11-Preview",
+      "searchRequest": {
+         "count": true,
+         "facets": [ "category,count:10,sort:count" ],
+         "filter": "rating gt 4.0",
+         "highlight": "title",
+         "highlightPostTag": "</em>",
+         "highlightPreTag": "<em>",
+         "minimumCoverage": null,
+         "orderby": "search.score() desc,rating desc",
+         "queryType": "simple",
+         "scoringParameters": [ "currentLocation--122.123,44.77233" ],
+         "scoringProfile": "sp",
+         "search": "nice hotels",
+         "searchFields": "title,description",
+         "searchMode": "any",
+         "select": "docId,title,description",
+         "skip": 0,
+         "top": 10
+      }
+   },
+   "responses": {
+      "200": {
+         "body": {
+            "@odata.count": 25,
+            "@search.facets": {
+               "category": [
+                  {
+                     "count": 1,
+                     "value": "Economy"
+                  },
+                  {
+                     "count": 1,
+                     "value": "Luxury"
+                  }
+               ]
+            },
+            "@search.nextPageParameters": {
+               "count": true,
+               "facets": [ "category,count:10,sort:count" ],
+               "filter": "rating gt 4.0",
+               "highlight": "title",
+               "highlightPostTag": "</em>",
+               "highlightPreTag": "<em>",
+               "minimumCoverage": null,
+               "orderby": "search.score() desc,rating desc",
+               "queryType": "simple",
+               "scoringParameters": [ "currentLocation--122.123,44.77233" ],
+               "scoringProfile": "sp",
+               "search": "nice hotels",
+               "searchFields": "title,description",
+               "searchMode": "any",
+               "select": "docId,title,description",
+               "skip": 2,
+               "top": 8
+            },
+            "value": [
+               {
+                  "@search.score": 1.50,
+                  "@search.highlights": {
+                     "title": [ "<em>Nice</em> <em>Hotel</em>" ]
+                  },
+                  "description": "Cheapest hotel in town",
+                  "docId": "1",
+                  "title": "Nice Hotel"
+               },
+               {
+                  "@search.score": 0.70,
+                  "@search.highlights": {
+                     "title": [ "Fancy <em>Hotel</em>" ]
+                  },
+                  "description": "Best hotel in town",
+                  "docId": "2",
+                  "title": "Fancy Hotel"
+               }
+            ],
+            "@odata.nextLink": "https://myservice.search.windows.net/indexes('myindex')/docs/search.post.search?api-version=2017-11-11-Preview"
+         }
+      }
+   }
+}