Add docs for test scenario (Azure#15437)

* Add docs for test scenario * fix markdown * update doc * update readme * update readme * improve folder structure * move errorCode reference * update * add brief introduction * fix doc * Add contentVersion * fix sample * add caution * fix link * change schema folder * features * fix command * fix * update png * add jsonpathopmove * update readme * refine schema Co-authored-by: Lei Ni <leni@microsoft.com> Co-authored-by: Ruoxuan Wang <52271048+ruowan@users.noreply.github.com>
ajparule · Aug 9, 2021 · f1f0483 · f1f0483
1 parent 56cd478
commit f1f0483
Show file tree

Hide file tree

Showing 22 changed files with 1,843 additions and 8 deletions.
diff --git a/documentation/samplefiles/Microsoft.YourServiceName/stable/YYYY-MM-DD/YourServiceCat.json b/documentation/samplefiles/Microsoft.YourServiceName/stable/YYYY-MM-DD/YourServiceCat.json
@@ -0,0 +1,234 @@
+{
+  "swagger": "2.0",
+  "info": {
+    "version": "2019-12-01",
+    "title": "YourServiceName",
+    "description": "Description of the new service",
+    "x-ms-code-generation-settings": {
+      "name": "YourServiceNameClient"
+    }
+  },
+  "host": "management.azure.com",
+  "schemes": [
+    "https"
+  ],
+  "consumes": [
+    "application/json"
+  ],
+  "produces": [
+    "application/json"
+  ],
+  "security": [
+    {
+      "azure_auth": [
+        "user_impersonation"
+      ]
+    }
+  ],
+  "securityDefinitions": {
+    "azure_auth": {
+      "type": "oauth2",
+      "authorizationUrl": "https://login.microsoftonline.com/common/oauth2/authorize",
+      "flow": "implicit",
+      "description": "Azure Active Directory OAuth2 Flow",
+      "scopes": {
+        "user_impersonation": "impersonate your user account"
+      }
+    }
+  },
+  "paths": {
+    "/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.YourServiceName/cats/{catName}": {
+      "get": {
+        "operationId": "Cats_Get",
+        "x-ms-examples": {
+          "GetCat": "./examples/CatsGet.json"
+        },
+        "description": "This is a sample get operation, please see guidelines in azure-rest-api-specs repository for more info",
+        "parameters": [
+          {
+            "$ref": "#/parameters/SubscriptionIdParameter"
+          },
+          {
+            "$ref": "#/parameters/ResourceGroupNameParameter"
+          },
+          {
+            "$ref": "#/parameters/ApiVersionParameter"
+          },
+          {
+            "$ref": "#/parameters/CatNameParameter"
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Describe the result of a successful operation.",
+            "schema": {
+              "$ref": "#/definitions/Cat"
+            }
+          },
+          "default": {
+            "description": "Error response describing why the operation failed.",
+            "schema": {
+              "$ref": "#/definitions/ErrorResponse"
+            }
+          }
+        }
+      },
+      "put": {
+        "operationId": "Cats_CreateOrUpdate",
+        "x-ms-examples": {
+          "UpdateCat": "./examples/CatsCreateOrUpdate.json"
+        },
+        "description": "This is a sample get operation, please see guidelines in azure-rest-api-specs repository for more info",
+        "parameters": [
+          {
+            "$ref": "#/parameters/SubscriptionIdParameter"
+          },
+          {
+            "$ref": "#/parameters/ResourceGroupNameParameter"
+          },
+          {
+            "$ref": "#/parameters/ApiVersionParameter"
+          },
+          {
+            "$ref": "#/parameters/CatNameParameter",
+          },
+          {
+            "name": "parameters",
+            "in": "body",
+            "description": "The parameters for creating or updating a cat.",
+            "required": true,
+            "schema": {
+              "$ref": "#/definitions/Cat"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Describe the result of a successful operation.",
+            "schema": {
+              "$ref": "#/definitions/Cat"
+            }
+          },
+          "default": {
+            "description": "Error response describing why the operation failed.",
+            "schema": {
+              "$ref": "#/definitions/ErrorResponse"
+            }
+          }
+        }
+      }
+    }
+  },
+  "definitions": {
+    "Result": {
+      "description": "Sample result definition",
+      "properties": {
+        "sampleProperty": {
+          "type": "string",
+          "description": "Sample property of type string"
+        }
+      }
+    },
+    "ErrorResponse": {
+      "description": "Error response.",
+      "properties": {
+        "error": {
+          "$ref": "#/definitions/ErrorDefinition",
+          "description": "The error details."
+        }
+      }
+    },
+    "ErrorDefinition": {
+      "description": "Error definition.",
+      "properties": {
+        "code": {
+          "description": "Service specific error code which serves as the substatus for the HTTP error code.",
+          "type": "string",
+          "readOnly": true
+        },
+        "message": {
+          "description": "Description of the error.",
+          "type": "string",
+          "readOnly": true
+        },
+        "details": {
+          "description": "Internal error details.",
+          "type": "array",
+          "items": {
+            "$ref": "#/definitions/ErrorDefinition"
+          },
+          "readOnly": true
+        }
+      }
+    },
+    "Cat": {
+      "description": "Sample cat model",
+      "properties": {
+        "id": {
+          "type": "string",
+          "description": "The id of the cat"
+        },
+        "location": {
+          "type": "string",
+          "description": "The location of the cat"
+        },
+        "name": {
+          "type": "string",
+          "description": "The name of the cat"
+        },
+        "type": {
+          "type": "string",
+          "description": "The type of the cat"
+        },
+        "properties": {
+          "$ref": "#/definitions/CatProperties"
+        }
+      }
+    },
+    "CatProperties": {
+      "description": "Sample cat properties model",
+      "properties": {
+        "fullName": {
+          "type": "string",
+          "description": "The full name of the cat"
+        },
+        "mateId": {
+          "type": "string",
+          "description": "The id of the cat's mate"
+        }
+      },
+      "required": ["name"]
+    }
+  },
+  "parameters": {
+    "SubscriptionIdParameter": {
+      "name": "subscriptionId",
+      "in": "path",
+      "required": true,
+      "type": "string",
+      "description": "The Azure subscription ID. This is a GUID-formatted string (e.g. 00000000-0000-0000-0000-000000000000)"
+    },
+    "ResourceGroupNameParameter": {
+      "name": "resourceGroupName",
+      "in": "path",
+      "required": true,
+      "type": "string",
+      "description": "The name of the resource group.",
+      "x-ms-parameter-location": "method"
+    },
+    "ApiVersionParameter": {
+      "name": "api-version",
+      "in": "query",
+      "required": true,
+      "type": "string",
+      "description": "The API version to be used with the HTTP request."
+    },
+    "CatNameParameter": {
+      "name": "catName",
+      "in": "path",
+      "required": true,
+      "type": "string",
+      "description": "The name of the cat."
+    }
+  }
+}
diff --git a/.../samplefiles/Microsoft.YourServiceName/stable/YYYY-MM-DD/examples/CatsCreateOrUpdate.json b/.../samplefiles/Microsoft.YourServiceName/stable/YYYY-MM-DD/examples/CatsCreateOrUpdate.json
@@ -0,0 +1,27 @@
+{
+  "parameters": {
+    "accountName": "sampleacct",
+    "resourceGroupName": "YourServiceNameClient",
+    "api-version": "2019-12-01",
+    "subscriptionId": "subid",
+    "catName": "Rococo",
+    "parameters": {
+      "properties": {
+        "fullName": "Rococo Sue"
+      }
+    }
+  },
+  "responses": {
+    "200": {
+      "body": {
+        "name": "Rococo",
+        "location": "westus",
+        "id": "/subscriptions/subid/resourceGroups/YourServiceNameClient/providers/Microsoft.YourServiceName/cats/Rococo",
+        "type": "Microsoft.YourServiceName/cats",
+        "properties": {
+          "fullName": "Rococo Sue"
+        }
+      }
+    }
+  }
+}
diff --git a/documentation/samplefiles/Microsoft.YourServiceName/stable/YYYY-MM-DD/examples/CatsGet.json b/documentation/samplefiles/Microsoft.YourServiceName/stable/YYYY-MM-DD/examples/CatsGet.json
@@ -0,0 +1,19 @@
+{
+  "parameters": {
+    "accountName": "sampleacct",
+    "resourceGroupName": "YourServiceNameClient",
+    "api-version": "2019-12-01",
+    "subscriptionId": "subid",
+    "catName": "Rococo"
+  },
+  "responses": {
+    "200": {
+      "body": {
+        "name": "Rococo",
+        "location": "westus",
+        "id": "/subscriptions/subid/resourceGroups/YourServiceNameClient/providers/Microsoft.YourServiceName/cats/Rococo",
+        "type": "Microsoft.YourServiceName/cats"
+      }
+    }
+  }
+}
diff --git a/...n/samplefiles/Microsoft.YourServiceName/stable/YYYY-MM-DD/examples/OperationGroupGet.json b/...n/samplefiles/Microsoft.YourServiceName/stable/YYYY-MM-DD/examples/OperationGroupGet.json
@@ -8,7 +8,6 @@
   "responses": {
     "200": {
       "body": {
-        "name": "sampleacct",
         "location": "uswest",
         "id": "/subscriptions/subid/resourceGroups/YourServiceNameClient/providers/Microsoft.YourServiceName/batchAccounts/sampleacct",
         "type": "Microsoft.YourServiceName/YourServiceName"

diff --git a/...on/samplefiles/Microsoft.YourServiceName/stable/YYYY-MM-DD/scenarios/testYourService.yaml b/...on/samplefiles/Microsoft.YourServiceName/stable/YYYY-MM-DD/scenarios/testYourService.yaml
@@ -0,0 +1,47 @@
+# yaml-language-server: $schema=https://raw.githubusercontent.com/Azure/azure-rest-api-specs/main/documentation/test-scenario/references/v1.0/schema.json
+
+scope: ResourceGroup
+testScenarios:
+  - description: Microsoft.YourService Test Operation Get
+    steps:
+      - step: Test Operation Get
+        exampleFile: ../examples/OperationGroupGet.json
+
+  - description: Microsoft.YourService Test Cat Create and Update
+    steps:
+      - step: Create cat Rococo
+        exampleFile: ../examples/CatsCreateOrUpdate.json
+        resourceName: cat0
+
+      - step: Get cat Rococo
+        exampleFile: ../examples/CatsGet.json
+
+      - step: Update full name
+        resourceName: cat0
+        resourceUpdate:
+          - replace: /properties/fullName
+            value: Rococo the Cat
+
+  - description: Microsoft.YourService Test Cat mate link
+    steps:
+      - step: Create cat Rococo
+        exampleFile: ../examples/CatsCreateOrUpdate.json
+        resourceName: cat0
+
+      - step: Create cat Baroque
+        exampleFile: ../examples/CatsCreateOrUpdate.json
+        resourceName: cat1
+        variables:
+          catName: Baroque
+        requestUpdate:
+          - replace: /parameters/properties/fullName
+            value: Baroque the Cat
+        outputVariables:
+          cat1Id:
+            fromResponse: /id
+
+      - step: Link cat Baroque to cat Rococo
+        resourceName: cat0
+        resourceUpdate:
+          - add: /properties/mateId
+            value: $(cat1Id)
diff --git a/documentation/samplefiles/readme.go.md b/documentation/samplefiles/readme.go.md
@@ -2,10 +2,25 @@
 
 These settings apply only when `--go` is specified on the command line.
 
-```yaml $(go) && $(track2)
-azure-arm: true
-license-header: MICROSOFT_MIT_NO_VERSION
-module-name: sdk/[[ServiceName]]/arm[[ServiceName]]
-module: github.com/Azure/azure-sdk-for-go/$(module-name)
-output-folder: $(go-sdk-folder)/$(module-name)
+```yaml $(go)
+go:
+  license-header: MICROSOFT_MIT_NO_VERSION
+  namespace: [[ServiceName]]
+  clear-output-folder: true
+```
+
+### Go multi-api
+
+``` yaml $(go) && $(multiapi)
+batch:
+  - tag: package-[[Version]][[-ReleaseState]]
+```
+
+### Tag: package-[[Version]][[-ReleaseState]] and go
+
+These settings apply only when `--tag=package-[[Version]][[-ReleaseState]] --go` is specified on the command line.
+Please also specify `--go-sdk-folder=<path to the root directory of your azure-sdk-for-go clone>`.
+
+```yaml $(tag) == 'package-[[Version]][[-ReleaseState]]' && $(go)
+output-folder: $(go-sdk-folder)/services[[/ReleaseState]]/$(namespace)/mgmt/[[Version]]/$(namespace)
 ```
diff --git a/documentation/samplefiles/samplereadme.md b/documentation/samplefiles/samplereadme.md
@@ -51,7 +51,7 @@ This is not used by Autorest itself.
 swagger-to-sdk:
   - repo: azure-sdk-for-python-track2
   - repo: azure-sdk-for-java
-  - repo: azure-sdk-for-go-track2
+  - repo: azure-sdk-for-go
   - repo: azure-sdk-for-js
   - repo: azure-resource-manager-schemas
   - repo: azure-cli-extensions