From be85078d71a120cc39dcb63ce8200f49b4377f96 Mon Sep 17 00:00:00 2001 From: Bruce Johnston Date: Fri, 8 Feb 2019 08:58:49 -0800 Subject: [PATCH] [Azure Search] Add Get Documents API (a.k.a. Lookup) to data plane API 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 --- ... SearchIndexAutocompleteDocumentsGet.json} | 0 ...SearchIndexAutocompleteDocumentsPost.json} | 2 +- .../examples/SearchIndexGetDocument.json | 19 +++++++ .../2017-11-11-preview/searchindex.json | 54 +++++++++++++++++-- .../Microsoft.Azure.Search.Data/readme.md | 25 ++++++++- 5 files changed, 94 insertions(+), 6 deletions(-) rename specification/search/data-plane/Microsoft.Azure.Search.Data/preview/2017-11-11-preview/examples/{SearchIndexGetAutocomplete.json => SearchIndexAutocompleteDocumentsGet.json} (100%) rename specification/search/data-plane/Microsoft.Azure.Search.Data/preview/2017-11-11-preview/examples/{SearchIndexPostAutocomplete.json => SearchIndexAutocompleteDocumentsPost.json} (94%) create mode 100644 specification/search/data-plane/Microsoft.Azure.Search.Data/preview/2017-11-11-preview/examples/SearchIndexGetDocument.json diff --git a/specification/search/data-plane/Microsoft.Azure.Search.Data/preview/2017-11-11-preview/examples/SearchIndexGetAutocomplete.json b/specification/search/data-plane/Microsoft.Azure.Search.Data/preview/2017-11-11-preview/examples/SearchIndexAutocompleteDocumentsGet.json similarity index 100% rename from specification/search/data-plane/Microsoft.Azure.Search.Data/preview/2017-11-11-preview/examples/SearchIndexGetAutocomplete.json rename to specification/search/data-plane/Microsoft.Azure.Search.Data/preview/2017-11-11-preview/examples/SearchIndexAutocompleteDocumentsGet.json diff --git a/specification/search/data-plane/Microsoft.Azure.Search.Data/preview/2017-11-11-preview/examples/SearchIndexPostAutocomplete.json b/specification/search/data-plane/Microsoft.Azure.Search.Data/preview/2017-11-11-preview/examples/SearchIndexAutocompleteDocumentsPost.json similarity index 94% rename from specification/search/data-plane/Microsoft.Azure.Search.Data/preview/2017-11-11-preview/examples/SearchIndexPostAutocomplete.json rename to specification/search/data-plane/Microsoft.Azure.Search.Data/preview/2017-11-11-preview/examples/SearchIndexAutocompleteDocumentsPost.json index 9bf10af1cee4..e693f6f07de8 100644 --- a/specification/search/data-plane/Microsoft.Azure.Search.Data/preview/2017-11-11-preview/examples/SearchIndexPostAutocomplete.json +++ b/specification/search/data-plane/Microsoft.Azure.Search.Data/preview/2017-11-11-preview/examples/SearchIndexAutocompleteDocumentsPost.json @@ -11,7 +11,7 @@ "highlightPostTag": "", "highlightPreTag": "", "minimumCoverage": 80, - "searchFields": ["title", "description"], + "searchFields": "title,description", "top": 10 } }, diff --git a/specification/search/data-plane/Microsoft.Azure.Search.Data/preview/2017-11-11-preview/examples/SearchIndexGetDocument.json b/specification/search/data-plane/Microsoft.Azure.Search.Data/preview/2017-11-11-preview/examples/SearchIndexGetDocument.json new file mode 100644 index 000000000000..50738b071d51 --- /dev/null +++ b/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" + } + } + } +} \ No newline at end of file diff --git a/specification/search/data-plane/Microsoft.Azure.Search.Data/preview/2017-11-11-preview/searchindex.json b/specification/search/data-plane/Microsoft.Azure.Search.Data/preview/2017-11-11-preview/searchindex.json index c51ac6cf9dfd..f9b1ff57fcc8 100644 --- a/specification/search/data-plane/Microsoft.Azure.Search.Data/preview/2017-11-11-preview/searchindex.json +++ b/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": { diff --git a/specification/search/data-plane/Microsoft.Azure.Search.Data/readme.md b/specification/search/data-plane/Microsoft.Azure.Search.Data/readme.md index 01646ac7ab7e..9bc5169457cd 100644 --- a/specification/search/data-plane/Microsoft.Azure.Search.Data/readme.md +++ b/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(), 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(> GetWithHttpMessagesAsync)/g, "$1$2" ). + replace( /(DeserializeObject)/g, "$1" ). + replace( /(var _result = new AzureOperationResponse)/g, "$1" ) ```