Merge branch 'master' of github.com:Azure/autorest into optional

Documentation/swagger-extensions.md

@@ -394,10 +394,14 @@ positionInOperation | `string` | **Optional, Default: first**. Specifies whether
 parameters | [Array of Parameter Objects](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#parameterObject) | The list of parameters that are used within the hostTemplate. This can include both reference parameters as well as explicit parameters. Note that "in" is **required** and **must be** set to **"path"**. The reference parameters will be treated as **global parameters** and will end up as property of the client.
 
 **Example**:
-Using both explicit and reference parameters
+- Using both explicit and reference parameters.
+   - Since "useSchemePrefix" is not specified, it's default value true will be applied. The user is expected to provide only the value of accountName. The generated code will fit it as a part of the url.
+   - Since "positionInOperation" with value "last" is specified, "accountName" will be the last required parameter in every method. "adlaJobDnsSuffixInPath" will be a property on the client as it is defined in the global parameters section and is referenced here.
+
 ```js
 "x-ms-parameterized-host": {
     "hostTemplate": "{accountName}.{adlaJobDnsSuffix}",
+    "positionInOperation": "last",
     "parameters": [
       {
         "name": "accountName",
@@ -423,10 +427,13 @@ Using both explicit and reference parameters
       "description": "Gets the DNS suffix used as the base for all Azure Data Lake Analytics Job service requests."
     }
 ```
-Using only explicit parameters
+- Using explicit parameters and specifying the positionInOperation and schemePrefix. 
+   - This means that accountName will be the first required parameter in all the methods and the user is expected to provide a url (protocol + accountName), since "useSchemePrfix" is set to false.
 ```js
 "x-ms-parameterized-host": {
     "hostTemplate": "{accountName}.mystaticsuffix.com",
+    "useSchemePrefix": false,
+    "positionInOperation": "first",
     "parameters": [
       {
         "name": "accountName",