Minor updates to description properties to improve docs (#3209)

* Update swagger for api-version 2018-03-01
 - add many missing examples
 - improve/complete descriptions and summaries

* Fix a handful of validation failures
Add/correct some response codes

* Fix back-compat for some error codes (leaving it inconsistent)
Change policyAssignment result for nonexistent delete by ID to match all other delete methods
Attempt to fix Travis FNF error

* Fix bracket bug in last commit

* Another attempt to fix Travis CI FNF error: simplifying the example file as much as possible.

* Another attempt to fix Travis FNF error (filename casing...)

* Putting back original example, modified during troubleshooting.

* Apply PR feedback (fix errors in a couple examples)

* Correct/improve wording in description properties.

* Update a few descriptions to improve the REST docs.

specification/resources/resource-manager/Microsoft.Authorization/stable/2018-03-01/policyAssignments.json

@@ -528,7 +528,7 @@
         },
         "policyDefinitionId": {
           "type": "string",
-          "description": "The ID of the policy definition."
+          "description": "The ID of the policy definition or policy set definition being assigned."
         },
         "scope": {
           "type": "string",
@@ -570,7 +570,7 @@
       "required": [
         "name"
       ],
-      "description": "The policy sku."
+      "description": "The policy sku. This property is optional, obsolete, and will be ignored."
     },
     "PolicyAssignment": {
       "properties": {
@@ -596,7 +596,7 @@
         },
         "sku": {
           "$ref": "#/definitions/PolicySku",
-          "description": "The policy sku."
+          "description": "The policy sku. This property is optional, obsolete, and will be ignored."
         }
       },
       "description": "The policy assignment.",
@@ -619,7 +619,7 @@
       "description": "List of policy assignments."
     },
     "ErrorResponse": {
-      "description": "Error reponse indicates ARM is not able to process the incoming request. The reason is provided in the error message.",
+      "description": "Error reponse indicates Azure Resource Manager is not able to process the incoming request. The reason is provided in the error message.",
       "type": "object",
       "properties": {
         "httpStatus": {

specification/resources/resource-manager/Microsoft.Authorization/stable/2018-03-01/policyDefinitions.json

@@ -378,7 +378,8 @@
           "PolicyDefinitions"
         ],
         "operationId": "PolicyDefinitions_ListByManagementGroup",
-        "description": "Gets all the policy definitions in a management group.",
+        "summary": "Retrieve policy definitions in a management group",
+        "description": "This operation retrieves a list of all the policy definitions in a given management group.",
         "x-ms-examples": {
           "List policy definitions by management group": {
             "$ref": "./examples/listPolicyDefinitionsByManagementGroup.json"

specification/resources/resource-manager/Microsoft.Authorization/stable/2018-03-01/policySetDefinitions.json

@@ -580,7 +580,7 @@
       "description": "List of policy set definitions."
     },
     "ErrorResponse": {
-      "description": "Error reponse indicates ARM is not able to process the incoming request. The reason is provided in the error message.",
+      "description": "Error reponse indicates Azure Resource Manager is not able to process the incoming request. The reason is provided in the error message.",
       "type": "object",
       "properties": {
         "httpStatus": {