[PowerBIDedicated] Elaborate description and examples on capacity mode (Azure#16131)

* Elaborate description and exampleson capacity mode

* PR fixes

* Revert changes for 2017 version

Author: laurent-mic

specification/powerbidedicated/resource-manager/Microsoft.PowerBIdedicated/stable/2021-01-01/examples/updateToGen2.json

@@ -0,0 +1,90 @@
+{
+  "parameters": {
+    "subscriptionId": "613192d7-503f-477a-9cfe-4efc3ee2bd60",
+    "resourceGroupName": "TestRG",
+    "dedicatedCapacityName": "azsdktest",
+    "api-version": "2021-01-01",
+    "capacityUpdateParameters": {
+      "sku": {
+        "name": "A1",
+        "tier": "PBIE_Azure"
+      },
+      "tags": {
+        "testKey": "testValue"
+      },
+      "properties": {
+        "mode": "Gen2"
+      }
+    }
+  },
+  "responses": {
+    "200": {
+      "headers": {},
+      "body": {
+        "id": "/subscriptions/613192d7-503f-477a-9cfe-4efc3ee2bd60/resourceGroups/TestRG/providers/Microsoft.PowerBIDedicated/capacities/azsdktest",
+        "location": "West US",
+        "name": "azsdktest",
+        "properties": {
+          "administration": {
+            "members": [
+              "[email protected]",
+              "[email protected]"
+            ]
+          },
+          "mode": "Gen2",
+          "provisioningState": "Provisioning",
+          "state": "Provisioning"
+        },
+        "sku": {
+          "name": "A1",
+          "tier": "PBIE_Azure"
+        },
+        "tags": {
+          "testKey": "testValue"
+        },
+        "systemData": {
+          "createdBy": "user1",
+          "createdByType": "User",
+          "createdAt": "2021-01-01T00:00:19.1234567Z",
+          "lastModifiedBy": "user2",
+          "lastModifiedByType": "User",
+          "lastModifiedAt": "2021-01-01T00:00:19.1234567Z"
+        }
+      }
+    },
+    "202": {
+      "headers": {},
+      "body": {
+        "id": "/subscriptions/613192d7-503f-477a-9cfe-4efc3ee2bd60/resourceGroups/TestRG/providers/Microsoft.PowerBIDedicated/capacities/azsdktest",
+        "location": "West US",
+        "name": "azsdktest",
+        "properties": {
+          "administration": {
+            "members": [
+              "[email protected]",
+              "[email protected]"
+            ]
+          },
+          "mode": "Gen2",
+          "provisioningState": "Provisioning",
+          "state": "Provisioning"
+        },
+        "sku": {
+          "name": "A1",
+          "tier": "PBIE_Azure"
+        },
+        "tags": {
+          "testKey": "testValue"
+        },
+        "systemData": {
+          "createdBy": "user1",
+          "createdByType": "User",
+          "createdAt": "2021-01-01T00:00:19.1234567Z",
+          "lastModifiedBy": "user2",
+          "lastModifiedByType": "User",
+          "lastModifiedAt": "2021-01-01T00:00:19.1234567Z"
+        }
+      }
+    }
+  }
+}

specification/powerbidedicated/resource-manager/Microsoft.PowerBIdedicated/stable/2021-01-01/powerbidedicated.json

@@ -204,6 +204,9 @@
         "x-ms-examples": {
           "Update capacity parameters": {
             "$ref": "./examples/updateCapacity.json"
+          },
+          "Update capacity to Generation 2": {
+            "$ref": "./examples/updateToGen2.json"
           }
         },
         "tags": [
@@ -857,7 +860,7 @@
           "description": "A collection of Dedicated capacity administrators"
         },
         "mode": {
-          "description": "The capacity mode.",
+          "description": "Specifies the generation of the Power BI Embedded capacity. If no value is specified, the default value 'Gen2' is used. [Learn More](https://docs.microsoft.com/power-bi/developer/embedded/power-bi-embedded-generation-2)",
           "type": "string",
           "enum": [
             "Gen1",