Per collection Swagger plus multiple changes to conform to fluent SDK conventions and bug fixes

[naveedaz]

1. Add per collection API version support
2. Add per collection swagger file support
3. Order swagger definitions and paths
4. Add missing descriptions to models
5. Bug fixes:
   • Too many variations of list operation names in Web App Swagger #431
   • Many required parameters are NOT being labeled as required (Web App Swagger) #432
   • List operations do not use the standard paged list (Web App Swagger) #433
   • Boolean parameters should be boolean, not string (Web App Swagger) #434
   • Many read only properties are NOT being labeled as read only (Web App Swagger) #435
   • Many list operations are modeled as Get operations (Web App Swagger) #436
   • Long running operations must be modeled as long running operations (Web App Swagger) #443
   • "Global_" should be removed and its "global" method should be applicable at the top level #473
   • checkNameAvailability should be exposed on the proper resource type collection model itself #474
   • validate should be exposed on the individual models  #475

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.
  • Validation errors from the Linter extension for VS Code have all been fixed for this spec. (Note: for large, previously checked in specs, there will likely be many errors shown. Please contact our team so we can set a timeframe for fixing these errors if your PR is not going to address them).
  • The spec follows the patterns described in the Swagger good patterns document unless the service API makes this impossible.

[tbombach]

General comment: for the future, could you add a Swashbuckle customization to remove deprecated: false (since it's the default)? I think omitting default values makes it easier for Swagger files to be consumed in general (even if it won't have a functional difference). Let's not tackle it for this review, just something for us to do later.

(same with empty consumes/produces sections)

[tbombach]

In https://github.com/naveedaz/azure-rest-api-specs/blob/1e97be15076e600610d10be3ebb1d33f137b01d9/arm-web/2016-03-01/AppServiceCertificateOrders.json#L284:

Could you expand this description? I'm not sure what CSM stands for

[tbombach]

We're starting to ask for more descriptive/useful descriptions (e.g. https://github.com/naveedaz/azure-rest-api-specs/blob/1e97be15076e600610d10be3ebb1d33f137b01d9/arm-web/2016-03-01/AppServiceCertificateOrders.json#L333 could provide more information about the parameter). I think instead of blocking this PR, I'd like to provide some slides from the documentation team that go into what they ask for. Let's plan on doing a doc quality pass in a future PR

[naveedaz]

Added an issue to track removal of sections that are repeated and have default values. #601

[naveedaz]

@tbombach For Documentation, we have been trying to enlist help from technical writers to clean it up and make it useful and descriptive. However, those resources were pulled into different projects, once we have them back we can address documentation issues more thoroughly. In the meantime, please do fwd the slides.

[tbombach]

@naveedaz Re: documentation - yes, I definitely understand. I want to bring up these kinds of issues for awareness that we want to tackle them, but we'll focus on getting this PR merged based for the scope of the fixes you listed (I'm through about half of the files right now)

[tbombach]

In https://github.com/naveedaz/azure-rest-api-specs/blob/1e97be15076e600610d10be3ebb1d33f137b01d9/arm-web/2016-03-01/AppServiceCertificateOrders.json#L324, the ResourceGroupName parameter is defined each time it's used in an operation. You can define it in the global parameters section and use x-ms-parameter-location: 'method' so that it's a method parameter anywhere it's referenced, not a property on the service client

If you'd rather fix that in a future PR (if it's outside the scope for this one), please open an issue for tracking it. It's not something that would prevent me from merging this one, and it might take a fair amount of work to change it for all specs

[naveedaz]

Thanks @tbombach. This PR is kind of a big reset, so future PRs should be smaller and more contained.

[tbombach]

@naveedaz Is it helpful to include comments in this PR for these issues as I see them? I understand that the goal of this one isn't to fix all of these issues, so I'd like to provide this info to you in an easy way for you to consume for later PRs. I'd be happy to open the issues myself if that saves you some time

[AutorestCI]

No modification for Ruby

[AutorestCI]

No modification for NodeJS

[AutorestCI]

No modification for Python