Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Search: Some Swagger specs are not linter-compliant or complete #1085

Closed
brjohnstmsft opened this issue Mar 30, 2017 · 6 comments
Closed

Search: Some Swagger specs are not linter-compliant or complete #1085

brjohnstmsft opened this issue Mar 30, 2017 · 6 comments
Assignees
@brjohnstmsft
Labels
P0 Search Service Attention Workflow: This issue is responsible by Azure service team. Service-team

Comments

@brjohnstmsft
Copy link
Member

Summary

Currently Azure Search has three Swagger specs per API version:

  • arm-search/.../search.json: This is the spec for the Azure Search Management REST API (a.k.a. -- control plane), exposed through ARM.
  • search/.../searchservice.json: This is one of the specs for the Azure Search Service REST API (a.k.a. -- data plane), exposed as a distinct endpoint with its own DNS name for each Search service provisioned by a customer via the control plane. This spec covers the top-level resources, all of which have model types that are fully known at design-time (i.e. -- they are part of the API and do not vary per customer).
  • search/../searchindex.json: This is the other spec for the Azure Search data plane. It covers the docs resource that exists for every (customer-defined) search index.

The intent of this issue is to capture and track all known issues with these specs, as of the following API versions:

  • Control plane: 2015-08-19
  • Data plane: 2016-09-01-Preview

Issues with search.json

  1. Currently the spec uses the standard Swagger examples property instead of x-ms-examples. This needs to be changed the next time we touch this spec.
  2. The last time we ran this spec against the linter was in November 2016. Likely the rules have changed since then, so we will need to re-run the linter and address any errors or warnings.

Issues with searchservice.json

We need to:

  1. Add x-ms-examples to all operations.
  2. Add descriptions to all operation responses.
  3. Add a default response to all operations.
  4. Re-run the linter and address any remaining errors or warnings.

Issues with searchindex.json

Same as the issues for searchservice.json, plus:

  1. Most of the API surface of the docs resource is not captured in this Swagger spec. This is because we haven't yet done the engineering work to figure out how to get AutoRest to generate acceptable code for the dynamically-typed data plane part of our API (something the old Hyak generator wasn't designed to do). This is a non-trivial amount of work for us, and is currently on hold pending higher business priorities.
@brjohnstmsft
Copy link
Member Author

FYI @vishrutshah

At this time we have no ETA for the above changes.

@brjohnstmsft brjohnstmsft mentioned this issue Mar 30, 2017
Merged
10 tasks
@salameer salameer added the P0 label Apr 4, 2017
@brjohnstmsft brjohnstmsft mentioned this issue May 23, 2017
Merged
marstr added a commit to marstr/azure-sdk-for-go that referenced this issue May 23, 2017
@marstr
Removing search packages as per brjohnstmsft
e0eff6e 
For more information, see Azure/azure-rest-api-specs#1085
@brjohnstmsft brjohnstmsft mentioned this issue Oct 14, 2017
Merged
marstr added a commit to marstr/azure-rest-api-specs that referenced this issue Oct 15, 2017
@marstr
Removing Search Data-Plane Go Config
ff80acd 
As requested by @brjohnstmsft in Azure#1787 and Azure#1085
marstr added a commit to marstr/azure-sdk-for-go that referenced this issue Oct 15, 2017
@marstr
Removing Search Data-Plane packages
2d73ca3 
As discussed in Azure/azure-rest-api-specs#1085 and Azure/azure-rest-api-specs#1787 by @brjohnstmsft
jhendrixMSFT pushed a commit that referenced this issue Oct 16, 2017
@marstr @jhendrixMSFT
Adding Go SDK Generation Configuration (#1787)
afcceaf 
* Adding Go Keyvault specification.

* Adding CDN Go config

* Adding Relay Go Config

* Adding Storage Go Config

* Adding App Insights Go Config.

* Adding APIManagment Go Config

* Adding Authorization Go Config

* Adding ContainerRegistry Go Config

* Fixing license-header tag in current work.

* Adding AnalysisServices Go Config

* Adding Automation Go Config

* Adding Batch Go Config

* Adding Billing Go Config

* Adding MediaServices Go Config

* Fixing Nit formatting issue.

* Adding CognitiveServices Go Config

* Adding Compute Go Config

* Adding Consumption Go Config

* Adding ContainerInstance Go Config

* Adding CosmosDB Go Config

* Adding CustomerInsights Go Config

* Adding DataFactory Go Config

* Adding DomainServices Go Config

* Adding EventGrid Go Config

* Adding EventHub Go Config

* Adding GraphRBAC Go Config

* Adding IoTHub Go Config

* Adding Logic Go Config

* Adding NotificationHub Go Config

* Adding Redis Go Config

* Adding Scheduler Go Config

* Adding Search Go Config

* Add ServerManagement Go Config

* Adding ServiceBus Go Config

* Adding StorSimple8000Series Go Config

* Adding StreamAnalytics Go Config

* Add TrafficManager Go Config

* Adding VisualStudio Go Config

* Review feedback

* More syntax fixes in Batch.

* Adding Advisor Go Config

* Adding Commerce Go Config

* Adding Datalake Go Config

* Fixing DataLake Store typo

* Adding DNS Go Config

* Adding DevTestLabs Go Config

* Adding HD Insight Go Config

* Adding Intune Go Config

* Adding Machine Learning Go Config

* Adding MySQL Go Config

* Fixing typo

* Adding Monitor Go Config

* Fixing Network package typo

* Adding Mobile Engagement Go Config

* Adding Operational Insights Go Config

* Adding PostgreSQL Go Config

* Adding PowerBIEmbedded Go Config

* Adding StorageImportExport Go Config

* Fixing billing output-folder typo

* Fixing advisor tag

* Adding Service Fabric Go Config

* Fixing Datalake Analytics Go Config

* Removing '_' from machine_learning Go path

* Adding missing parameter specification docs

* Removing Search Data-Plane Go Config

As requested by @brjohnstmsft in #1787 and #1085
marstr added a commit to Azure/azure-sdk-for-go that referenced this issue Oct 16, 2017
@marstr
Adding Multi-API Version support packages. (#812)
2e898b2 
* Adding Multi-API Version support packages.

* Fixing Billing Output

* Generating Datalake Analytics Management package

* Renaming machine_learning -> machinelearning

* Removing Search Data-Plane packages

As discussed in Azure/azure-rest-api-specs#1085 and Azure/azure-rest-api-specs#1787 by @brjohnstmsft

* Adding web package

* Adding resources

* Adding resource health

* Adding SQL packages

* Adding Operations Management

* Adding Market Place Ordering:wq

* Adding Service-Map
@brjohnstmsft brjohnstmsft mentioned this issue Jan 8, 2018
Closed
@brjohnstmsft
Copy link
Member Author

Update: The issues mentioned above for the management plane (search.json) have been resolved. The issues with the data plane specs remain.

brjohnstmsft added a commit to brjohnstmsft/azure-rest-api-specs that referenced this issue Feb 6, 2018
@brjohnstmsft
[Azure Search] Moving 2016-09-01-preview spec from private repo
48d30eb 
Prior to the reorganization of the azure-rest-api-specs repo structure, the
Swagger specs for the Azure Search data plane API version 2016-09-01-preview
lived in the search-service branch of the azure-rest-api-specs-pr repo. Now
that there is a place for preview/incomplete Swagger specs in the public repo,
we'd like to move this spec there so all the specs are in one place.

The specs themselves have not changed; This is just a repo-to-repo copy.

Like all Azure Search data plane specs, these are incomplete. See this issue
for details: Azure#1085
@brjohnstmsft brjohnstmsft mentioned this issue Feb 6, 2018
Merged
10 tasks
fearthecowboy pushed a commit that referenced this issue Feb 6, 2018
@brjohnstmsft @fearthecowboy
[Azure Search] Moving 2016-09-01-preview spec from private repo (#2427)
6fa97c2 
* [Azure Search] Moving 2016-09-01-preview spec from private repo

Prior to the reorganization of the azure-rest-api-specs repo structure, the
Swagger specs for the Azure Search data plane API version 2016-09-01-preview
lived in the search-service branch of the azure-rest-api-specs-pr repo. Now
that there is a place for preview/incomplete Swagger specs in the public repo,
we'd like to move this spec there so all the specs are in one place.

The specs themselves have not changed; This is just a repo-to-repo copy.

Like all Azure Search data plane specs, these are incomplete. See this issue
for details: #1085

* [Azure Search] Adding 2016-09-01-preview config to readme.md
@brjohnstmsft
Copy link
Member Author

brjohnstmsft commented May 9, 2018 •
edited
Loading

Update: All issues around validation and examples have been addressed. However, searchindex.json is still incomplete. We are currently working on this.

@bsiegel bsiegel added the Service Attention Workflow: This issue is responsible by Azure service team. label Sep 26, 2018
@brjohnstmsft
Copy link
Member Author

Update: searchindex.json now completely covers the Azure Search data plane for versions 2017-11-11-Preview and 2019-05-06. Keeping this open as we still need to fill in some descriptions for responses and fix some validation issues.

@akning-ms
Copy link
Contributor

Hi @brjohnstmsft can we close this issue now?

@brjohnstmsft
Copy link
Member Author

@akning-ms Yes, the specs are now complete.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees

@brjohnstmsft brjohnstmsft

Labels
P0 Search Service Attention Workflow: This issue is responsible by Azure service team. Service-team
Projects
None yet
Milestone
No milestone
Development

No branches or pull requests
5 participants
@bsiegel @brjohnstmsft @vishrutshah @salameer @akning-ms