[Azure Search] Swagger specs and examples for data plane GA version 2… #2843

brjohnstmsft · 2018-04-10T01:22:09Z

…017-11-11

This updates the Swagger specs for the new GA version of the Azure Search data
plane. These new specs are exact copies of the 2016-09-01-Preview specs, with
the api-version changed. Same for the examples.

This checklist is used to make sure that common issues in a pull request are addressed. This will expedite the process of getting your pull request merged and avoid extra work on your part to fix issues discovered during the review process.

PR information

The title of the PR is clear and informative.
There are a small number of commits, each of which have an informative message. This means that previously merged commits do not appear in the history of the PR. For information on cleaning up the commits in your pull request, see this page.
Except for special cases involving multiple contributors, the PR is started from a fork of the main repository, not a branch.
If applicable, the PR references the bug/issue that it fixes.
Swagger files are correctly named (e.g. the api-version in the path should match the api-version in the spec).

Quality of Swagger

I have read the contribution guidelines.
My spec meets the review criteria:
- The spec conforms to the Swagger 2.0 specification.
- The spec follows the guidelines described in the Swagger checklist document.
- Validation tools were run on swagger spec(s) and have all been fixed in this PR.

…017-11-11 This updates the Swagger specs for the new GA version of the Azure Search data plane. These new specs are exact copies of the 2016-09-01-Preview specs, with the api-version changed. Same for the examples.

AutorestCI · 2018-04-10T01:22:44Z

Automation for azure-sdk-for-go

Nothing to generate for azure-sdk-for-go

AutorestCI · 2018-04-10T01:22:55Z

Automation for azure-libraries-for-java

Nothing to generate for azure-libraries-for-java

AutorestCI · 2018-04-10T01:22:55Z

Automation for azure-sdk-for-python

Nothing to generate for azure-sdk-for-python

AutorestCI · 2018-04-10T01:23:01Z

Automation for azure-sdk-for-node

Nothing to generate for azure-sdk-for-node

brjohnstmsft · 2018-04-11T21:00:27Z

@jianghaolu -- Can you please look at this today?

jianghaolu · 2018-04-10T18:15:07Z

...ation/search/data-plane/Microsoft.Azure.Search.Service/preview/2017-11-11/searchservice.json

+          "description": "A value indicating whether the original token will be kept. Default is false."
+        }
+      },
+      "description": "Converts alphabetic, numeric, and symbolic Unicode characters which are not in the first 127 ASCII characters (the \"Basic Latin\" Unicode block) into their ASCII equivalents, if such equivalents exist. T


This parameter is required but is missing in the examples.

I can't tell from the context -- Which parameter are you referring to?

jianghaolu · 2018-04-11T22:15:49Z

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

+      "x-ms-parameter-location": "client"
+    },
+    "SearchDnsSuffixParameter": {
+      "name": "searchDnsSuffix",


This required parameter is not provided in any example.

Do downstream consumers of these examples do anything useful with x-ms-parameterized-host parameters like this one? For example, when we start generating REST API documentation from Swagger (we aren't yet for our data plane, for historical reasons), will the examples in the docs put this parameter and searchServiceName in the host name part of the request URL where it should be?

The doc team is using the x-ms-examples for generating examples in the docs. I think they are doing that. Here is an example for the Storage Management API. Please contact the doc team for feature requests or any feedback.

@amarzavery Do you happen to know if these KeyVault docs are auto-generated as well? This seems to be an example of what we're hoping for.

jianghaolu · 2018-04-11T22:18:38Z

...ation/search/data-plane/Microsoft.Azure.Search.Service/preview/2017-11-11/searchservice.json

+          "description": "A value indicating whether the original token will be kept. Default is false."
+        }
+      },
+      "description": "Converts alphabetic, numeric, and symbolic Unicode characters which are not in the first 127 ASCII characters (the \"Basic Latin\" Unicode block) into their ASCII equivalents, if such equivalents exist. T


Please add this required parameter to the examples.

I can't tell from the context -- Which parameter are you referring to?

jianghaolu · 2018-04-11T22:32:17Z

...icrosoft.Azure.Search.Service/preview/2017-11-11/examples/SearchServiceCreateDataSource.json

+            },
+            "dataDeletionDetectionPolicy": {
+                "@odata.type": "#Microsoft.Azure.Search.SoftDeleteColumnDeletionDetectionPolicy",
+                "softDeleteColumnName": "isDeleted",


These 2 properties are not defined in the type definition of "DataDeletionDetectionPolicy".

This is a polymorphic type. Note the use of the discriminator property in DataDeletionDetectionPolicy. The value of @odata.type indicates that this object is of type SoftDeleteColumnDeletionPolicy. If you look at the definition of SoftDeleteColumnDeletionPolicy in the Swagger, you'll see the softDeleteColumnName and softDeleteMarkerValue properties are defined. Also note the use of x-ms-discriminator-value and allOf in SoftDeleteColumnDeletionPolicy.

Please ensure your validation tools understand polymorphism, as it is a crucial feature for modeling data plane APIs using AutoRest.

jianghaolu · 2018-04-11T22:38:12Z

...ne/Microsoft.Azure.Search.Service/preview/2017-11-11/examples/SearchServiceListIndexers.json

+                        "description": "another cool indexer",  
+                        "dataSourceName": "myblobdatasource",  
+                        "targetIndexName": "orders",  
+                        "schedule": { },  


"interval" is required here.

I think the example is meant to show that the schedule itself is not required. I'll remove it.

jianghaolu · 2018-04-11T22:44:26Z

The GitHub review link is broken - The major valid error the tool is reporting is missing required parameters from the global "parameters" section, like "Prefer", or missing required parameters on the parameterized host, like "searchDnsSuffix".

azuresdkciprbot · 2018-04-12T22:51:19Z

Hi There,

I am the AutoRest Linter Azure bot. I am here to help. My task is to analyze the situation from the AutoRest linter perspective. Please review the below analysis result:

File: specification/search/data-plane/Microsoft.Azure.Search.Data/readme.md
Before the PR: Warning(s): 0 Error(s): 0
After the PR: Warning(s): 0 Error(s): 0

File: specification/search/data-plane/Microsoft.Azure.Search.Service/readme.md
Before the PR: Warning(s): 1 Error(s): 0
After the PR: Warning(s): 1 Error(s): 0

AutoRest Linter Guidelines | AutoRest Linter Issues | Send feedback

Thanks for your co-operation.

azuresdkciprbot · 2018-04-12T23:02:01Z

Hi There,

I am the AutoRest Linter Azure bot. I am here to help. My task is to analyze the situation from the AutoRest linter perspective. Please review the below analysis result:

File: specification/search/data-plane/Microsoft.Azure.Search.Data/readme.md
Before the PR: Warning(s): 0 Error(s): 0
After the PR: Warning(s): 0 Error(s): 0

File: specification/search/data-plane/Microsoft.Azure.Search.Service/readme.md
Before the PR: Warning(s): 0 Error(s): 0
After the PR: Warning(s): 0 Error(s): 0

AutoRest Linter Guidelines | AutoRest Linter Issues | Send feedback

Thanks for your co-operation.

azuresdkci assigned jianghaolu Apr 10, 2018

azuresdkci requested a review from jianghaolu April 10, 2018 01:22

jianghaolu suggested changes Apr 11, 2018

View reviewed changes

[Azure Search] Adding searchDnsSuffix and Prefer to examples

c6fcba9

amarzavery mentioned this pull request Apr 12, 2018

Fix model validation issues for Search dataplane swagger spec Azure/oav#234

Closed

jianghaolu approved these changes Apr 12, 2018

View reviewed changes

jianghaolu merged commit c9c0734 into Azure:master Apr 12, 2018

brjohnstmsft deleted the search-2017-11-11 branch April 12, 2018 18:55

brjohnstmsft mentioned this pull request Apr 18, 2018

[Azure Search] Prepare 5.0 data plane SDK for release Azure/azure-sdk-for-net#4246

Merged

9 tasks

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[Azure Search] Swagger specs and examples for data plane GA version 2… #2843

[Azure Search] Swagger specs and examples for data plane GA version 2… #2843

brjohnstmsft commented Apr 10, 2018 •

edited

Loading

AutorestCI commented Apr 10, 2018 •

edited

Loading

AutorestCI commented Apr 10, 2018 •

edited

Loading

AutorestCI commented Apr 10, 2018 •

edited

Loading

AutorestCI commented Apr 10, 2018 •

edited

Loading

brjohnstmsft commented Apr 11, 2018

jianghaolu Apr 10, 2018

brjohnstmsft Apr 12, 2018

jianghaolu Apr 11, 2018

brjohnstmsft Apr 12, 2018

amarzavery Apr 12, 2018

brjohnstmsft Apr 12, 2018

jianghaolu Apr 11, 2018

brjohnstmsft Apr 12, 2018

jianghaolu Apr 11, 2018

brjohnstmsft Apr 12, 2018

jianghaolu Apr 11, 2018

brjohnstmsft Apr 12, 2018

jianghaolu commented Apr 11, 2018

azuresdkciprbot commented Apr 12, 2018

azuresdkciprbot commented Apr 12, 2018

[Azure Search] Swagger specs and examples for data plane GA version 2… #2843

[Azure Search] Swagger specs and examples for data plane GA version 2… #2843

Conversation

brjohnstmsft commented Apr 10, 2018 • edited Loading

PR information

Quality of Swagger

AutorestCI commented Apr 10, 2018 • edited Loading

Automation for azure-sdk-for-go

AutorestCI commented Apr 10, 2018 • edited Loading

Automation for azure-libraries-for-java

AutorestCI commented Apr 10, 2018 • edited Loading

Automation for azure-sdk-for-python

AutorestCI commented Apr 10, 2018 • edited Loading

Automation for azure-sdk-for-node

brjohnstmsft commented Apr 11, 2018

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jianghaolu commented Apr 11, 2018

azuresdkciprbot commented Apr 12, 2018

azuresdkciprbot commented Apr 12, 2018

brjohnstmsft commented Apr 10, 2018 •

edited

Loading

AutorestCI commented Apr 10, 2018 •

edited

Loading

AutorestCI commented Apr 10, 2018 •

edited

Loading

AutorestCI commented Apr 10, 2018 •

edited

Loading

AutorestCI commented Apr 10, 2018 •

edited

Loading