-
Notifications
You must be signed in to change notification settings - Fork 5.6k
Adding swagger spec for RecoveryServices.SiteRecovery service. #1209
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.
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
Conversation
|
@avneeshrai, |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Is there a reason why this is not being added to the directory here instead
|
Note for the reviewers:
Except on "code": "OperationsAPIImplementationValidation" we had closed on all other issues in the current thread. About the implementation of operations API, we expect operations API for our provider Microsoft.RecoveryServices to be present in https://github.com/Azure/azure-rest-api-specs/blob/08f0f317ccb89b86f552232bd8fce02f98889463/arm-recoveryservices/2016-06-01/swagger/vaultusages.json spec (which is already there). Let me know if we have a reason to duplicate it here.
Error seen in validator tool: { code: 'RESPONSE_VALIDATION_ERROR',
Fields having “null” value are not allowed. Error seen in validator tool: { code: 'RESPONSE_VALIDATION_ERROR',
Error in validator tool { code: 'RESPONSE_VALIDATION_ERROR', I have sent a mail to @veronicagg , @salameer with details on closures. |
|
@dsgouda These projects are managed by separate teams just that the provider is same. For example you can see are in different directories. |
|
@dsgouda have added you to the mail thread. |
|
| "$ref": "#/parameters/ResourceName" | ||
| }, | ||
| { | ||
| "$ref": "#/para |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
should this be boolean? a property with the same name and description is boolean at https://github.com/Azure/azure-rest-api-specs/pull/1209/files#diff-f47a33852eff8e5696392b354d7a3636R11347
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Same as above. We have exception from your side in email thread.
| "$ref": "#/parameters/ResourceName" | ||
| }, | ||
| { | ||
| "$ref": "#/para |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
should this be boolean? a property with the same name and description is boolean at https://github.com/Azure/azure-rest-api-specs/pull/1209/files#diff-f47a33852eff8e5696392b354d7a3636R11347
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
As we had discussed in our e-mail discussions, it was not possible for us to take any change at the service end. We had decided take up any such change whenever we come up with new version in the service. We had exception from your side on this.
| "$ref": "#/parameters/ResourceName" | ||
| }, | ||
| { | ||
| "$ref": "#/para |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
https://travis-ci.org/Azure/azure-rest-api-specs/jobs/230461195#L2611 do you want to consider flattening here?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Same. We had decided not to go for flattening.
| "$ref": "#/parameters/ResourceName" | ||
| }, | ||
| { | ||
| "$ref": "#/para |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
https://travis-ci.org/Azure/azure-rest-api-specs/jobs/230461195#L2599 do you want to consider flattening here?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Same. We had decided not to go for flattening.
| "$ref": "#/parameters/ResourceName" | ||
| }, | ||
| { | ||
| "$ref": "#/para |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
https://travis-ci.org/Azure/azure-rest-api-specs/jobs/230461195#L2587 do you want to consider flattening here?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
We had decided not to go for flattening and closure is in our mail thread.
| "$ref": "#/parameters/ResourceName" | ||
| }, | ||
| { | ||
| "$ref": "#/para |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
do you need this model to be different in the body compared to the response model - see https://travis-ci.org/Azure/azure-rest-api-specs/jobs/230461195#L1340
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
We already closed on this in our mail thread with exception from your side. For context, we had approval from ARM board which was shared on the email.
Our mail thread can be referred for details.
|
About examples:
I would raise the issues as you had suggested for these scenarios. |
|
@veronicagg Please find inline responses in bolditalics for your queries. Is this version of the service already deployed to ARM? Regarding linter validation errors, our tool has been updated since the time of our last conversation, please review the following: Consider flattening: https://travis-ci.org/Azure/azure-rest-api-specs/jobs/230461195#L2491 Error at https://travis-ci.org/Azure/azure-rest-api-specs/jobs/230461195#L1975 |
|
Raised issues for problems with examples stated above: |
|
@avneeshrai Just to clarify, 1) the tools have been updated, so issues that may have been false positives before may not be now, so it's good to re-evaluate. 2) it's good to have this documented in this PR. |
| } | ||
| } | ||
| }, | ||
| "/Subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.RecoveryServices/vaults/{resourceName}/replicationFabrics/{fabricName}/replicationvCenters/{vCenterName}/operationresults/{jobName}": { |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
is there a reason for this API to be exposed? How are you expecting customers to use it?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I was not really sure on inclusion of these APIs (operationresults) in spec. Only rationale i had behind including them in swagger spec was that customers who are looking at swagger spec as documentation of our APIs should get to know what all exists in our entire API surface and what API he can call if he wants to track some operation's result.
However, i don't see much utility for consumers of generated sdk. What is the recommendation here?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
unless there's a specific reason to include them, we're generally not including them. For long running operations, the sdk generated code will provide methods that can poll and obtain the results as appropriate.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Have removed all operationresult apis in the latest commit.
| } | ||
| } | ||
| }, | ||
| "/Subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.RecoveryServices/vaults/{resourceName}/replicationFabrics/{fabricName}/replicationStorageClassifications/{storageClassificationName}/replicationStorageClassificationMappings/{storageClassificationMappingName}/operationresults/{jobName}": { |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
is there a reason for this API to be exposed? How are you expecting customers to use it?
similar question for other "operationresults" apis
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Same as before, I was not really sure on inclusion of these APIs (operationresults) in spec. Only rationale i had behind including them in swagger spec was that customers who are looking at swagger spec as documentation of our APIs should get to know what all exists in our entire API surface and what API he can call if he wants to track some operation's result.
However, i don't see much utility for consumers of generated sdk. What is the recommendation here?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
see above, I would remove them, if you don't have a specific reason to include them.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Removed
|
@veronicagg I get the reasons now. Thanks for clarifying :) |
| "$ref": "#/parameters/SubscriptionId" | ||
| }, | ||
| { | ||
| "name": "fabricName", |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
you could define this parameter in the global parameters section and have a reference here, if you're using it multiple times. And similarly for any other parameters that you're planning to reuse.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Given the kind of usage we have for parameters like fabricName, containerName they change in general for every second operation our customers can call, to minimize confusion we have kept all parameter which would remain constant for a instance of initialized client in global list and others as local. This is also consistent with the current usage.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Ok, up to you, my suggestion was mostly for your convenience, so you didn't need to repeat and modify everywhere you needed an update in the swagger.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
@veronicagg We are generating the spec automatically. So that is not an issue for us :)
| } | ||
| } | ||
| }, | ||
| "deprecated": false, |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
no need to include deprecated: false, as it's the default value.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Sure, removing this from all operations.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
sounds good.
…n ids and 2) Taking PR comments: removing redundant deprecated field from operations.
|
@veronicagg Addressed the comments with new commits. |
|
@avneeshrai - Please fix the following issues too -
|
1) Introducing operations API with corresponding example. 2) Fixing required field from patch input (UpdateRecoveryPlanInput).
|
@ravbhatnagar Taken all comments that we could. Please find the responses:
|
…d corresponding examples. 2) Converting some fields from boolean to string and making corresponding changes in examples.
|
@veronicagg @ravbhatnagar I have responded to all the comments (fixing issues wherever possible). |
veronicagg
left a comment
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
couple more questions, inline, rest looks good to me.
| "networkType": "VmNetworkAsInput", | ||
| "networkId": "/subscriptions/c183865e-6077-46f2-a3b1-deb0f4f4650a/resourceGroups/siterecoveryProd1/providers/Microsoft.Network/virtualNetworks/vnetavrai", | ||
| "skipTestFailoverCleanup": false, | ||
| "skipTestFailoverCleanup": "false", |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
If this is really a boolean value, should this property be represented as boolean on the swagger? then you can use boolean true/false.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
@veronicagg Service is expecting this as string. Its an intentional change. We realized this while trying to validate a variance of testfailover.
| }, | ||
| "skipTestFailoverCleanup": { | ||
| "description": "A value indicating whether the test failover cleanup is to be skipped.", | ||
| "type": "boolean" |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
is this change intentional? is the value not a boolean?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Service is expecting this as string. Its an intentional change.
|
@veronicagg Responded. |
veronicagg
left a comment
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Thanks for the fixes! LGTM I'm approving from my side, we just need approval from @ravbhatnagar on the ARM side.
|
@avneeshrai - The following comment from you is not correct - |
|
@ravbhatnagar Thanks for the response and explanation Gaurav. That was a gap in our understanding then. Would try taking this up whenever we come up with new service version for breaking changes. @veronicagg As now we don't have any open actionable item left, can we have this PR merged please :) |
|
No modification for Ruby |
|
No modification for NodeJS |
|
No modification for Python |
Adding swagger spec for RecoveryServices.SiteRecovery service (2016-08-10).
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
api-versionin the path should match theapi-versionin the spec).Quality of Swagger
This change is