Updating documentation for Microsoft.VisualStudio with project resour…

[niblak]

…ce APIs. Corrections to existing 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.

[msftclas]

@niblak,
Thanks for your contribution as a Microsoft full-time employee or intern. You do not need to sign a CLA.
Thanks,
Microsoft Pull Request Bot

[niblak]

I am not sure how best to express the fact that these two properties are required (ProcessTemplateId and VersionControlOption).

Also, there's a relatively static range of values that are accepted for these. If they were formal parameters I'd consider using x-ms-enum in the RP spec to list all possible values, but in this particular case I am not sure how to express that in documentation.

[balajikris]

I made a comment about this here. I think that should work, but you could quickly verify that by generating C# library using autorest and viewing the definition for ProjectResource

[niblak]

Thanks, I'll give that a try.

Is it possible to use the enum semantics on non-string types? ProcessTemplateId is actually a GUID, and the only accepted values are 6B724908-EF14-45CF-84F8-768B5384DA45, ADCC42AB-9882-485E-A3ED-7678F01F66BC, 27450541-8E31-4150-9947-DC59F998FC01.

From looking at other RP specs and the Swagger docs, I don't see a way to assign a friendly name to these (the IDs correspond to Scrum, Agile and Cmmi process templates).

[balajikris]

you are correct that there isn't a way to do this as of today. For the future, I hear that there is a proposal to expand the scope of x-ms-enum to accommodate this kind of friendly name assignment.

[balajikris]

you could model this like so:

       "properties": {
         "properties": {
           "ProcessTemplateId": { "required": true },
           "VersionControlOption": { "required": true },
           "properties": {
               "type": "object",
    	       "additionalProperties": {
			"type": "string"
		 },
		 "x-ms-client-flatten": true
           },
          "x-ms-client-flatten": true
         }
       }

[balajikris]

@niblak - The CI job found some errors with the new examples you added for the operations that are being added by this PR. See here
If you scroll all the way to the end, you can see that the last 4-5 failing examples were the ones you added. Could you please update your sample to make validation pass?

[balajikris]

@niblak -- I can see you are working on this, can you please tag me in a comment after you are done fixing the validation errors? Thanks.

[niblak]

@balajikris sorry about all the pushes.

I've resolved most of the example errors but am confused on the remaining two: INVALID_RESPONSE_BODY and INVALID_REQUEST_PARAMETER.

What am I missing here? It seems to be complaining about properties that are actually part of the response/request body for our API.

Latest PR build here.

[balajikris]

This should be removed

[balajikris]

Hey @niblak -

Sure, Its complaining because you have plan as an input to your updateproject call but the schema doesn't say anything about plan being an input to the api call. This is probably a result of copy pasting from another example? For e.g. see /UpdateExtensionResource.json example, plan is one of the inputs but in this case, the spec defines it as one of the input params.

[azuresdkciprbot]

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/visualstudio/resource-manager/readme.md
Before the PR: Warning(s): 4 Error(s): 0
After the PR: Warning(s): 6 Error(s): 0

AutoRest Linter Guidelines | AutoRest Linter Issues

Send feedback and make AutoRest Linter Azure Bot smarter day by day!

Thanks for your co-operation.

[niblak]

Thanks @balajikris. That was the problem and the CI build is passing now. Build #10 is failing due to a null ref, should I be concerned about this one?

The syntax for specifying ProcessTemplateId and VersionControlOption as required didn't seem to work unfortunately (failed both the PR build and C# client generation). For now, I've just added the list of valid values to the method summary. Not ideal, but there seems to be precedent for this in other RP specs.

[azuresdkciprbot]

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/visualstudio/resource-manager/readme.md
Before the PR: Warning(s): 4 Error(s): 0
After the PR: Warning(s): 6 Error(s): 0

AutoRest Linter Guidelines | AutoRest Linter Issues

Send feedback and make AutoRest Linter Azure Bot smarter day by day!

Thanks for your co-operation.

[balajikris]

@niblak - don't worry about the null ref on the build. Seems like a bug in the tool. CI looks much nicer now, thanks for making hte changes 👍 Will review again in a bit

[balajikris]

@niblak - If you are all done here, I'm ready to pull this in. Let me know. Thanks.

[niblak]

@balajikris Good to go. Thanks for the review!

[AutorestCI]

No modification for AutorestCI/azure-sdk-for-node

[AutorestCI]

No modification for AutorestCI/azure-sdk-for-ruby

[AutorestCI]

No modification for AutorestCI/azure-sdk-for-python