Merge pull request Azure#52 from veronicagg/merge-public

Merging public to private as of 3/29/2017 2:51 PM
matthchr · Mar 29, 2017 · 3a4edcc · 3a4edcc
2 parents 239733f + 9d6f47a
commit 3a4edcc
Show file tree

Hide file tree

Showing 262 changed files with 45,797 additions and 3,572 deletions.
diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md
@@ -1,12 +1,8 @@
 # Contributing to azure-rest-api-specs
-First, thank you for contributing to our Azure specs repository! Specs are the basis for generating Azure SDKs in multiple different languages, Azure CLIs for interacting with the services, and can provide documentation for these services.
+First, thank you for contributing to Azure specs repository! Swagger specs are the basis for generating Azure SDKs in multiple different languages, Azure CLIs for interacting with the services, and can provide documentation for these services.
 
 ## Basics
-In the Azure Developer Experience workflow, you are at Step 3:
-
-[API Design Review](https://github.com/Azure/adx-documentation-pr#begin-api-design-review) -> [Engage with ADX team](https://github.com/Azure/adx-documentation-pr/blob/master/README.md#engage-with-adx-team) -> _**[Swagger specification](https://github.com/Azure/adx-documentation-pr#create-swagger-specification)**_ -> [SDKs](https://github.com/Azure/adx-documentation-pr#sdks) -> [CLIs](https://github.com/Azure/adx-documentation-pr#clis)
-
-If you're a spec author looking for information about all of of the repositories and steps in the pipeline, go back to the [adx-documentation-pr](https://github.com/Azure/adx-documentation-pr) repository. Make sure to [join the Github Azure organization](http://aka.ms/azuregithub) to get access to that repo.
+If you're a spec author looking for information about all of of the repositories and steps in the pipeline, go to the [adx-documentation-pr](https://github.com/Azure/adx-documentation-pr) repository. Make sure to [join the Github Azure organization](http://aka.ms/azuregithub) to get access to that repo.
 
 ## Table of Contents
 [Before starting](#before-starting)
@@ -29,7 +25,7 @@ If you're a spec author looking for information about all of of the repositories
 ## Before starting
 
 ### Onboarding
-Make sure that your Github account is part of the Azure organization. [Use this page](aka.ms/azuregithub) to link your account.
+Make sure that your Github account is part of the Azure organization. [Use this page](http://aka.ms/azuregithub) to link your account.
 
 Before cloning this repository, please make sure you have started in our [documentation repository adx-documentation-pr](https://github.com/Azure/adx-documentation-pr) (you will only have access to that page if you are part of the Azure organization).
 
@@ -50,11 +46,9 @@ Swagger files are simply JSON files that follow the [OpenAPI Specification](http
 ### Documentation
 The [/documentation](../documentation/) folder contains many resources for writing Swagger files.
 
-The [Swagger Good Patterns](../documentation/swagger-good-patterns.md) page is intended as a guide for different scenarios. If you know the service behavior that you're trying to model (e.g. PUT/PATCH/GET responses and request schemas, or modeling long running operations), that document is structured to make it easy to find our recommendations.
-
-The [Reference Documentation](../documentation/creating-swagger.md) page contains lots of information about each part of a Swagger file and how to structure it correctly for code generation. If you're looking for an explanation of what a part of Swagger relates to your service or how it's used to generate code, that document is the right place to go.
+The [Swagger Checklist](../documentation/swagger-checklist.md) page is intended as a guide for different scenarios. If you know the service behavior that you're trying to model (e.g. PUT/PATCH/GET responses and request schemas, or modeling long running operations), that document is structured to make it easy to find our recommendations.
 
-The [Linter](../documentation/linter.md) page has instructions for downloading our extension for VS Code and links to explanations for each validation error or warning.
+The [Reference Documentation](../documentation/creating-swagger.md) page contains lots of information about each part of a Swagger file and how to structure it correctly for code generation. If you're looking for an explanation on what a part of Swagger relates to your service or how it's used to generate code, that document is the right place to go.
 
 ### Filenames and folder structure
 - Swagger spec for every api-version should be in a separate folder named with the api-version.
@@ -63,14 +57,13 @@ The [Linter](../documentation/linter.md) page has instructions for downloading o
 ### Tools for writing Swagger
 As JSON files, specs can be modified in any text editor that you choose. We have some recommendations that can make editing these files easier.
 
-- _**Recommended**_ Our [Linter extension for VS Code](../documentation/linter.md) provides validation, go to definition support, HTML preview of the spec, and other ease-of-use improvements.
-- Visual Studio can also provide a nice experience for editing JSON, though it takes extra work to use the JSON schema that defines Swagger files. Additionally, there will be extra work later to make sure any validation rules are followed. Both of these are automatically handled with the extension for VS Code.
+- _**Recommended**_ Visual Studio Code.
+- Visual Studio Code can provide a nice experience for editing JSON, though it takes extra work to use the JSON schema that defines Swagger files. 
 
 ### Tools for validating Swagger
-There are some tools that can help you make sure your spec doesn't contain basic errors. The more of these issues that are caught before the PR is sent, the quicker the turnaround to merging the PR will be. 
+There are some tools that can help you make sure your spec conforms to guidelines. The more of these issues that are caught before the PR is sent, the quicker the turnaround to merging the PR will be. 
 
-- _**Recommended**_ Our [Linter extension for VS Code](../documentation/linter.md) provides validation for common issues we see in specs. If we see any of the issues during the review process, we will ask you to use this extension before we continue reviewing.
-- `AutoRest.exe` will output the same errors as the VS Code extension if you run it from the command line. AutoRest is used in the [next step in the pipeline, SDK generation](https://github.com/Azure/adx-documentation-pr#sdks). If you add the `-ValidationLevel Warning` flag or `-Verbose`, the command line output will include validation messages. See the [AutoRest documentation](https://github.com/Azure/autorest/blob/master/Documentation/cli.md) for more info.
+- _**Recommended**_ Please take a look at the [validation tools for swagger checklist] (https://github.com/Azure/azure-rest-api-specs/blob/master/documentation/swagger-checklist.md#validation-tools-for-swagger-checklist) section. 
 - The [OpenAPI Initiative Swagger editor](http://editor.swagger.io/#/) will help find basic issues in a Swagger file. However, we apply a higher bar than this validator - just because this site doesn't show errors doesn't mean the spec is ready to merge. 
 - Similarly, this online [schema validator](https://json-schema-validator.herokuapp.com/) can help find basic errors. Again, we apply a higher bar than this validator - just because this site doesn't show errors doesn't mean the spec is ready to merge. 
   * In the upper left box, paste the [swagger schema from here](https://github.com/swagger-api/swagger-spec/blob/master/schemas/v2.0/schema.json)
@@ -93,26 +86,13 @@ Use the git tools you have available to you, such as amend, rebase, etc.
 
 
 ## Review process
-We review spec PRs to maintain a high bar of quality for all products that will be generated from these specs (including SDKs in all languages, CLIs and documentation). It's critical that spec files are both sytactically and semantically correct, as well as conform to common patterns that make it possible to generate SDKs and CLIs that are usable for customers. Since specs are the base input for all of these products, the review process starts with PRs to this repository.
-
-### SLA
-Our SLA for reviewing specs is **2 business days**. We are committed to either merging the PR or providing you with a set of changes that are required before we can merge. Please be aware that the process can take longer if there are major changes requested after the initial review (since we will need to review the spec again).
-
-### Review Criteria
-This section lists what we look for when reviewing a PR. This constantly changes as we discover issues in specs that cause SDK or CLI issues. Standard patterns for common scenarios also change as we support more functionality in generated code or try to improve the experience for users of the SDKs.
+We review spec PRs to maintain a high bar of quality for all products that will be generated from these specs (including SDKs in all languages, CLIs and documentation). It's critical that spec files are both sytactically and semantically correct, as well as conform to common patterns that make it possible to generate SDKs and CLIs that are usable for customers. Since specs are the base input for all of these products, the review process starts with PRs to this repository. Please refer to [Swagger Review Process](https://github.com/Azure/adx-documentation-pr/wiki/Swagger-Review-Process) for more details.
 
-The following criteria are ordered from least to most stringent. The expectation is that every spec in a PR will be correct JSON, syntactically correct, will semantically agree with the service it applies to, and will follow the recommended patterns except for special circumstances.
+The expectation is that every spec in a PR will be correct JSON, syntactically correct, will semantically agree with the service it applies to, and will follow the recommended patterns.
 
 #### Basic JSON correctness
 A spec file must be valid JSON, according to the [JSON specification](https://tools.ietf.org/html/rfc7159). It must also be a valid Swagger file, according to the [OpenAPI Specification](http://swagger.io/specification/). Finally, it must also conform to the [schema that AutoRest applies](https://raw.githubusercontent.com/Azure/autorest/master/schema/swagger-extensions.json).
 
-**Recommendation**:  Use our [Linter extension for VS Code](../documentation/linter.md) when editing your spec. It will show JSON errors and use the correct Swagger schema to the file.
-
-#### Static analysis
-There are certain issues in spec files that make it impossible to generate working SDK code or usable SDKs, CLIs or documentation. These go beyond JSON or Swagger schema correctness, since a Swagger file could correctly describe an API yet still generate a bad SDK.
-
-**Recommendation**: Use our [Linter extension for VS Code](../documentation/linter.md) when editing your spec. It will catch these errors automatically and underline the file wherever there are errors.
-
 #### Semantic correctness
 Your spec file must correctly represent your service. Even if a spec passes all of the rules listed above, it might not accurately describe the service that it is intended to describe. This could include 
 - Incorrect schemas for responses or requests (both missing and superfluous properities)
@@ -124,7 +104,3 @@ Making sure that the spec is correct from a semantic point of view requires doma
 
 **Recommendation**: Check each operation, parameter, schema, property to make sure it accurately models the service API. Refer back to the [Reference documentation](../documentation/creating-swagger.md) for more details on every part of Swagger.
 
-#### Good patterns
-Following good patterns are an even higher standard than semantic correctness. These ensure that we provide a good experience across all Azure SDKs and CLIs. We manually check to make sure your spec follows these patterns, and we expect that any author sending a PR has checked their spec by hand as well.
-
-**Recommendation**: Refer to our [Swagger Recommended Patterns](../documentation/swagger-good-patterns.md) page. We expect that a spec will follow these patterns by default unless there is a good reason to deviate (e.g. the service behaves differently from the Azure API Guidelines for an old api-version).
diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md
@@ -11,5 +11,5 @@ This checklist is used to make sure that common issues in a pull request are add
 - [ ] I have read the [contribution guidelines](https://github.com/Azure/azure-rest-api-specs/blob/master/.github/CONTRIBUTING.md).
 - [ ] My spec meets the review criteria:
   - [ ] The spec conforms to the [Swagger 2.0 specification](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md).
-  - [ ] Validation errors from the [Linter extension for VS Code](https://github.com/Azure/azure-rest-api-specs/blob/master/documentation/linter.md) 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](https://github.com/Azure/azure-rest-api-specs/blob/master/documentation/swagger-good-patterns.md) document unless the service API makes this impossible.
+  - [ ] The spec follows the guidelines described in the [Swagger checklist](../documentation/swagger-checklist.md) document.
+  - [ ] [Validation tools](https://github.com/Azure/azure-rest-api-specs/blob/master/documentation/swagger-checklist.md#validation-tools-for-swagger-checklist) were run on swagger spec(s) and have all been fixed in this PR. 
diff --git a/.travis.yml b/.travis.yml
@@ -27,8 +27,8 @@ matrix:
     - env: MODE=semantic PR_ONLY=true
     - env: MODE=model PR_ONLY=true
 before_install:
-#  - docker pull lmazuel/swagger-to-sdk
-#  - python -c "import os; print('\n'.join(v for v in os.environ.keys() if v.startswith('TRAVIS')))" > /tmp/env_file
+  - docker pull lmazuel/swagger-to-sdk
+  - python -c "import os; print('\n'.join(v for v in os.environ.keys() if v.startswith('TRAVIS')))" > /tmp/env_file
   - sudo apt-get update
   - sudo apt-get install libunwind8 libicu52 -y
 install:

diff --git a/README.md b/README.md
@@ -7,23 +7,18 @@
 This repository is the canonical source for REST API specifications for Microsoft Azure.
 
 ## Basics
-In the Azure Developer Experience workflow, you are at Step 3:
-
-[API Design Review](https://github.com/Azure/adx-documentation-pr#begin-api-design-review) -> [Engage with ADX team](https://github.com/Azure/adx-documentation-pr/blob/master/README.md#engage-with-adx-team) -> _**[Swagger specification](https://github.com/Azure/adx-documentation-pr#create-swagger-specification)**_ -> [SDKs](https://github.com/Azure/adx-documentation-pr#sdks) -> [CLIs](https://github.com/Azure/adx-documentation-pr#clis)
-
-If you're a spec author looking for information about all of of the repositories and steps in the pipeline, go back to the [adx-documentation-pr](https://github.com/Azure/adx-documentation-pr) repository. Make sure to [join the Github Azure organization](http://aka.ms/azuregithub) to get access to that repo.
+If you're a spec author looking for information about all of of the repositories and steps in the pipeline, go to the [adx-documentation-pr](https://github.com/Azure/adx-documentation-pr) repository. Make sure to [join the Github Azure organization](http://aka.ms/azuregithub) to get access to that repo.
 
 ## Getting started
 - Our [Contribution guidelines](./.github/CONTRIBUTING.md) walks you through the process of contributing to this repository.
 - The [/documentation](./documentation/) folder contains reference documentation for all aspects of Swagger and our recommended patterns. Start with the [Creating Swagger](./documentation/creating-swagger.md) page.
-- If you are using **Swashbuckle** to generate a swagger spec from your .NET WEB API then please take a look at this [repo]( https://github.com/Azure/swashbuckle-resource-provider).
 
 ## Directory Structure
 
 The structure of the directory should strictly follow these rules:
-- The top level folder must be the service name
+- If the Rest end point is for management plane(going through ARM end point) then the top level folder must be the "arm-<service_name>". Else top folder name must be "<service_name>".
 - The second level must be the API versions
-- The third level must be the format of the specification
+- The third level must be the format of the specification (ex. swagger)
 - The fourth level must be the specifications
 
 The structure should appear like so:
@@ -65,7 +60,7 @@ The structure should appear like so:
 Currently, the specifications are expected to be in Swagger JSON format
 
 ## Next steps
-The next step in the process after a spec is completed is to generate SDKs. Go to the [SDKs section](https://github.com/Azure/adx-documentation-pr#sdks) of the Azure Developer Experience guide for more information.
+The next step in the process after a spec is completed is to generate SDKs and API reference documentation. Go to the [Azure Developer Experience guide](https://github.com/Azure/adx-documentation-pr) for more information.
 
 ---
 _This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/). For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or contact [opencode@microsoft.com](mailto:opencode@microsoft.com) with any additional questions or comments._
diff --git a/arm-advisor/2017-03-31/examples/CreateSuppression.json b/arm-advisor/2017-03-31/examples/CreateSuppression.json
@@ -0,0 +1,29 @@
+{
+  "parameters": {
+    "resourceUri": "resourceUri",
+    "recommendationId": "recommendationId",
+    "name": "suppressionName1",
+    "suppressionContract": {
+      "id": "/resourceUri/providers/Microsoft.Advisor/recommendations/recommendationId/suppressions/suppressionName1",
+      "name": "suppressionName1",
+      "type": "Microsoft.Advisor/suppressions",
+      "properties": {
+        "ttl": "07:00:00:00"
+      }
+    },
+    "api-version": "2017-03-31"
+  },
+  "responses": {
+    "200": {
+      "body": {
+        "id": "/resourceUri/providers/Microsoft.Advisor/recommendations/recommendationId/suppressions/suppressionName1",
+        "name": "suppressionName1",
+        "type": "Microsoft.Advisor/suppressions",
+        "properties": {
+          "suppressionId": "suppresionId",
+          "ttl": "07:00:00:00"
+        }
+      }
+    }
+  }
+}
diff --git a/arm-advisor/2017-03-31/examples/DeleteSuppression.json b/arm-advisor/2017-03-31/examples/DeleteSuppression.json
@@ -0,0 +1,12 @@
+{
+  "parameters": {
+    "resourceUri": "resourceUri",
+    "recommendationId": "recommendationId",
+    "name": "suppressionName1",
+    "api-version": "2017-03-31"
+  },
+  "responses": {
+    "204": {
+    }
+  }
+}
diff --git a/arm-advisor/2017-03-31/examples/GenerateRecommendations.json b/arm-advisor/2017-03-31/examples/GenerateRecommendations.json
@@ -0,0 +1,14 @@
+{
+  "parameters": {
+    "subscriptionId": "subscriptionId",
+    "api-version": "2017-03-31"
+  },
+  "responses": {
+    "202": {
+      "headers": {
+        "Location": "https://management.azure.com/subscriptions/subscriptionId/providers/Microsoft.Microsoft.Advisor/generateRecommendations/recGUID?api-version=2017-03-31",
+        "Retry-After": "60"
+      }
+    }
+  }
+}
diff --git a/arm-advisor/2017-03-31/examples/GetRecommendationDetail.json b/arm-advisor/2017-03-31/examples/GetRecommendationDetail.json
@@ -0,0 +1,28 @@
+{
+  "parameters": {
+    "resourceUri": "resourceUri",
+    "recommendationId": "recommendationId",
+    "api-version": "2017-03-31"
+  },
+  "responses": {
+    "200": {
+      "body": {
+        "id": "/resourceUri/providers/Microsoft.Advisor/recommendations/recommendationId",
+        "name": "recommendationId",
+        "properties": {
+          "category": "HighAvailability",
+          "impact": "Medium",
+          "impactedField": "Microsoft.Compute/availabilitySets",
+          "impactedValue": "armavset",
+          "lastUpdated": "2017-02-24T22:24:43.3216408Z",
+          "risk": "Warning",
+          "shortDescription": {
+            "problem": "This availability set is not configured for fault tolerance",
+            "solution": "To ensure high availability add one or more virtual machines to this availability set"
+          }
+        },
+        "type": "Microsoft.Advisor/recommendations"
+      }
+    }
+  }
+}