<commit_before># AutoRest Extensions for OpenAPI 2.0

### Introduction

The following documents describes AutoRest specific vendor extensions for [OpenAPI 2.0](https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md) schema. Some of the extensions are only applicable to Microsoft Azure and as such are only available in Azure code generators (e.g. Azure.CSharp, Azure.NodeJS, etc.).

### Generic Extensions

- [x-ms-code-generation-settings](#x-ms-code-generation-settings) - enables passing code generation settings via OpenAPI definition (_deprecated! Please use configuration files instead._)
- [x-ms-skip-url-encoding](#x-ms-skip-url-encoding) - skips URL encoding for path and query parameters
- [x-ms-enum](#x-ms-enum) - additional metadata for enums
- [x-ms-parameter-grouping](#x-ms-parameter-grouping) - groups method parameters in generated clients
- [x-ms-parameter-location](#x-ms-parameter-location) - provides a mechanism to specify that the global parameter is actually a parameter on the operation and not a client property.
- [x-ms-paths](#x-ms-paths) - alternative to [Paths Object](https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md#pathsObject) that allows [Path Item Object](https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md#pathItemObject) to have query parameters for non pure REST APIs
- [x-ms-client-name](#x-ms-client-name) - allows control over identifier names used in client-side code generation for parameters and schema properties.
- [x-ms-external](#x-ms-external) - allows specific [Definition Objects](https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md#definitionsObject) to be excluded from code generation
- [x-ms-discriminator-value](#x-ms-discriminator-value) - maps discriminator value on the wire with the definition name.
- [x-ms-client-flatten](#x-ms-client-flatten) - flattens client model property or parameter.
- [x-ms-parameterized-host](#x-ms-parameterized-host) - replaces the fixed host with a host template that can be replaced with variable parameters.
- [x-ms-mutability](#x-ms-mutability) - provides insight to Autorest on how to generate code. It doesn't alter the modeling of what is actually sent on the wire.
- [x-ms-examples](#x-ms-examples) - describes the format for specifying examples for request and response of an operation in an OpenAPI definition.
- [x-ms-error-response](#x-ms-error-response) - indicates whether the response status code should be treated as an error response
- [x-ms-text](#x-ms-text) - XML helper for scenario with attributes and text on the same XML node
- [x-ms-client-default](#x-ms-client-default) - Set default value for properties and parameters
- [x-ms-pageable](#x-ms-pageable) - allows paging through lists of data.
- [x-ms-long-running-operation](#x-ms-long-running-operation) - indicates that the operation implemented Long Running Operation pattern as defined by the [Resource Manager API](https://msdn.microsoft.com/en-us/library/azure/dn790568.aspx).
- [x-nullable](#x-nullable) - when `true`, specifies that `null` is a valid value for the associated schema
- [x-ms-header-collection-prefix](#x-ms-header-collection-prefix) - Handle collections of arbitrary headers by distinguishing them with a specified prefix.

### Microsoft Azure Extensions (available in most generators only when using `--azure-arm`)

- [x-ms-odata](#x-ms-odata) - indicates the operation includes one or more [OData](http://www.odata.org/) query parameters.
- [x-ms-azure-resource](#x-ms-azure-resource) - indicates that the [Definition Schema Object](https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md#schemaObject) is a resource as defined by the [Resource Manager API](https://msdn.microsoft.com/en-us/library/azure/dn790568.aspx)
- [x-ms-request-id](#x-ms-request-id) - allows to overwrite the request id header name
- [x-ms-client-request-id](#x-ms-client-request-id) - allows to overwrite the client request id header name

# Generic Extensions

## x-ms-code-generation-settings

`x-ms-code-generation-settings` extension on `info` element enables passing code generation settings via the OpenAPI definition.

**Parent element**: [Info Object](https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md#infoObject)

**Schema**:

| Field Name |        Type        | Description                                                                                                                            |
| ---------- | :----------------: | -------------------------------------------------------------------------------------------------------------------------------------- |
| .\*        | `string` or `bool` | **Required**. Field name should be a valid autorest.exe parameter. Value should be a valid string value or boolean for flag parameters |

**Example**:

```json5
"info": {
   "x-ms-code-generation-settings": {
      "header": "MIT",
      "internalConstructors": true,
      "useDateTimeOffset": true
   }
}
```

## x-ms-skip-url-encoding

By default, `path` parameters will be URL-encoded automatically. This is a good default choice for user-provided values. This is not a good choice when the parameter is provided from a source where the value is known to be URL-encoded. The URL encoding is NOT an idempotent operation. For example, the percent character "%" is URL-encoded as "%25". If the parameter is URL-encoded again, "%25" becomes "%2525". Mark parameters where the source is KNOWN to be URL-encoded to prevent the automatic encoding behavior.

**Parent element**: [Parameter Object](https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md#parameterObject)

**Schema**:
`true|false`

**Example**:

```json5
"parameters": [
  {
    "name": "databaseName",
    "in": "path",
    "type": "string",
    "required": true,
    "x-ms-skip-url-encoding": true
  }
]
```

## x-ms-enum

Enum definitions in OpenAPI indicate that only a particular set of values may be used for a property or parameter. When the property is represented on the wire as a string, it would be a natural choice to represent the property type in C# and Java as an enum. However, not all enumeration values should necessarily be represented as strongly typed enums - there are additional considerations, such as how often expected values might change, since adding a new value to a strongly typed enum is a breaking change requiring an updated API version. Additionally, there is some metadata that is required to create a useful enum, such as a descriptive name, which is not represented in vanilla OpenAPI. For this reason, enums are not automatically turned into strongly typed enum types - instead they are rendered in the documentation comments for the property or parameter to indicate allowed values. To indicate that an enum will rarely change and that C#/Java enum semantics are desired, use the `x-ms-enum` extension. Note that depending on the code generation language the behavior of this extension may differ.

In C# and Java, an enum type is generated and is declared as the type of the related request/response object. The enum is serialized as the string expected by the REST API.

**Parent element**: [Parameter Object](https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md#parameterObject), [Schema Object](https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md#schemaObject), [Items Object](https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md#itemsObject), or [Header Object](https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md#headerObject)

**Schema**:

| Field Name    |                          Type                           | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| ------------- | :-----------------------------------------------------: | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| name          |                        `string`                         | **Required**. Specifies the name for the Enum.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| modelAsString |                        `boolean`                        | **Default: false** When set to `true` the enum will be modeled as a string. No validation will happen. When set to `false`, it will be modeled as an enum if that language supports enums. Validation will happen, irrespective of support of enums in that language.                                                                                                                                                                                                                                                                                 |
| values        | `[{ value: any, description?: string, name?: string }]` | **Default: undefined** When set, this will override the values specified with `enum`, while also enabling further customization. We recommend still specifying `enum` as a fallback for consumers that don't understand `x-ms-enum`. Each item in `x-ms-enum` corresponds to an enum item. Property `value` is mandatory and corresponds to the value one would also have specified using `enum`. Properties `description` and `name` are optional. `name` allows overriding the name of the enum value that would usually be derived from the value. |

**Example**:

```yaml
accountType:
  type: string
  enum:
    - Standard_LRS
    - Standard_ZRS
    - Standard_GRS
    - Standard_RAGRS
    - Premium_LRS
  x-ms-enum:
    name: AccountType
    modelAsString: false
    values:
      - value: Standard_LRS
        description: Locally redundant storage.
        name: StandardLocalRedundancy
      - value: Standard_ZRS
        description: Zone-redundant storage.
      - value: Standard_GRS
        name: StandardGeoRedundancy
      - value: Standard_RAGRS
      - value: Premium_LRS
```

### Single value enum as a constant

- If the **single value** enum is a **required** model property or a **required** parameter then it is always treated as a constant. The `x-ms-enum` extension **is ignored**.
  - Explanation: The above condition specifies that the server always expects the model property or the parameter and with a specific value. Hence, it makes sense to treat it as a constant. In the future, if more values are added to the enum then, it is a breaking change to the API provided by the client library.
- If the **single value** enum is an **optional** model property or an **optional** parameter and if `x-ms-enum` extension is provided then it will be honoured.

## x-ms-parameter-grouping

By default operation parameters are generated in the client as method arguments. This behavior can sometimes be undesirable when the number of parameters is high. `x-ms-parameter-grouping` extension is used to group multiple primitive parameters into a composite type to improve the API.<commit_msg>Update current behavior of x-ms-enum in docs (#4352)<commit_after># AutoRest Extensions for OpenAPI 2.0

### Introduction

The following documents describes AutoRest specific vendor extensions for [OpenAPI 2.0](https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md) schema. Some of the extensions are only applicable to Microsoft Azure and as such are only available in Azure code generators (e.g. Azure.CSharp, Azure.NodeJS, etc.).

### Generic Extensions

- [x-ms-code-generation-settings](#x-ms-code-generation-settings) - enables passing code generation settings via OpenAPI definition (_deprecated! Please use configuration files instead._)
- [x-ms-skip-url-encoding](#x-ms-skip-url-encoding) - skips URL encoding for path and query parameters
- [x-ms-enum](#x-ms-enum) - additional metadata for enums
- [x-ms-parameter-grouping](#x-ms-parameter-grouping) - groups method parameters in generated clients
- [x-ms-parameter-location](#x-ms-parameter-location) - provides a mechanism to specify that the global parameter is actually a parameter on the operation and not a client property.
- [x-ms-paths](#x-ms-paths) - alternative to [Paths Object](https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md#pathsObject) that allows [Path Item Object](https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md#pathItemObject) to have query parameters for non pure REST APIs
- [x-ms-client-name](#x-ms-client-name) - allows control over identifier names used in client-side code generation for parameters and schema properties.
- [x-ms-external](#x-ms-external) - allows specific [Definition Objects](https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md#definitionsObject) to be excluded from code generation
- [x-ms-discriminator-value](#x-ms-discriminator-value) - maps discriminator value on the wire with the definition name.
- [x-ms-client-flatten](#x-ms-client-flatten) - flattens client model property or parameter.
- [x-ms-parameterized-host](#x-ms-parameterized-host) - replaces the fixed host with a host template that can be replaced with variable parameters.
- [x-ms-mutability](#x-ms-mutability) - provides insight to Autorest on how to generate code. It doesn't alter the modeling of what is actually sent on the wire.
- [x-ms-examples](#x-ms-examples) - describes the format for specifying examples for request and response of an operation in an OpenAPI definition.
- [x-ms-error-response](#x-ms-error-response) - indicates whether the response status code should be treated as an error response
- [x-ms-text](#x-ms-text) - XML helper for scenario with attributes and text on the same XML node
- [x-ms-client-default](#x-ms-client-default) - Set default value for properties and parameters
- [x-ms-pageable](#x-ms-pageable) - allows paging through lists of data.
- [x-ms-long-running-operation](#x-ms-long-running-operation) - indicates that the operation implemented Long Running Operation pattern as defined by the [Resource Manager API](https://msdn.microsoft.com/en-us/library/azure/dn790568.aspx).
- [x-nullable](#x-nullable) - when `true`, specifies that `null` is a valid value for the associated schema
- [x-ms-header-collection-prefix](#x-ms-header-collection-prefix) - Handle collections of arbitrary headers by distinguishing them with a specified prefix.

### Microsoft Azure Extensions (available in most generators only when using `--azure-arm`)

- [x-ms-odata](#x-ms-odata) - indicates the operation includes one or more [OData](http://www.odata.org/) query parameters.
- [x-ms-azure-resource](#x-ms-azure-resource) - indicates that the [Definition Schema Object](https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md#schemaObject) is a resource as defined by the [Resource Manager API](https://msdn.microsoft.com/en-us/library/azure/dn790568.aspx)
- [x-ms-request-id](#x-ms-request-id) - allows to overwrite the request id header name
- [x-ms-client-request-id](#x-ms-client-request-id) - allows to overwrite the client request id header name

# Generic Extensions

## x-ms-code-generation-settings

`x-ms-code-generation-settings` extension on `info` element enables passing code generation settings via the OpenAPI definition.

**Parent element**: [Info Object](https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md#infoObject)

**Schema**:

| Field Name |        Type        | Description                                                                                                                            |
| ---------- | :----------------: | -------------------------------------------------------------------------------------------------------------------------------------- |
| .\*        | `string` or `bool` | **Required**. Field name should be a valid autorest.exe parameter. Value should be a valid string value or boolean for flag parameters |

**Example**:

```json5
"info": {
   "x-ms-code-generation-settings": {
      "header": "MIT",
      "internalConstructors": true,
      "useDateTimeOffset": true
   }
}
```

## x-ms-skip-url-encoding

By default, `path` parameters will be URL-encoded automatically. This is a good default choice for user-provided values. This is not a good choice when the parameter is provided from a source where the value is known to be URL-encoded. The URL encoding is NOT an idempotent operation. For example, the percent character "%" is URL-encoded as "%25". If the parameter is URL-encoded again, "%25" becomes "%2525". Mark parameters where the source is KNOWN to be URL-encoded to prevent the automatic encoding behavior.

**Parent element**: [Parameter Object](https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md#parameterObject)

**Schema**:
`true|false`

**Example**:

```json5
"parameters": [
  {
    "name": "databaseName",
    "in": "path",
    "type": "string",
    "required": true,
    "x-ms-skip-url-encoding": true
  }
]
```

## x-ms-enum

Enum definitions in OpenAPI indicate that only a particular set of values may be used for a property or parameter. When the property is represented on the wire as a string, it would be a natural choice to represent the property type in C# and Java as an enum. However, not all enumeration values should necessarily be represented as strongly typed enums - there are additional considerations, such as how often expected values might change, since adding a new value to a strongly typed enum is a breaking change requiring an updated API version. Additionally, there is some metadata that is required to create a useful enum, such as a descriptive name, which is not represented in vanilla OpenAPI. For this reason, enums are not automatically turned into strongly typed enum types - instead they are rendered in the documentation comments for the property or parameter to indicate allowed values. To indicate that an enum will rarely change and that C#/Java enum semantics are desired, use the `x-ms-enum` extension. Note that depending on the code generation language the behavior of this extension may differ.

In C# and Java, an enum type is generated and is declared as the type of the related request/response object. The enum is serialized as the string expected by the REST API.

**Parent element**: [Parameter Object](https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md#parameterObject), [Schema Object](https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md#schemaObject), [Items Object](https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md#itemsObject), or [Header Object](https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md#headerObject)

**Schema**:

| Field Name    |                          Type                           | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| ------------- | :-----------------------------------------------------: | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| name          |                        `string`                         | **Required**. Specifies the name for the Enum.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| modelAsString |                        `boolean`                        | **Default: true** When set to `true` the enum will be modeled as a string. No validation will happen. When set to `false`, it will be modeled as an enum if that language supports enums. Validation will happen, irrespective of support of enums in that language.                                                                                                                                                                                                                                                                                  |
| values        | `[{ value: any, description?: string, name?: string }]` | **Default: undefined** When set, this will override the values specified with `enum`, while also enabling further customization. We recommend still specifying `enum` as a fallback for consumers that don't understand `x-ms-enum`. Each item in `x-ms-enum` corresponds to an enum item. Property `value` is mandatory and corresponds to the value one would also have specified using `enum`. Properties `description` and `name` are optional. `name` allows overriding the name of the enum value that would usually be derived from the value. |

**Example**:

```yaml
accountType:
  type: string
  enum:
    - Standard_LRS
    - Standard_ZRS
    - Standard_GRS
    - Standard_RAGRS
    - Premium_LRS
  x-ms-enum:
    name: AccountType
    modelAsString: false
    values:
      - value: Standard_LRS
        description: Locally redundant storage.
        name: StandardLocalRedundancy
      - value: Standard_ZRS
        description: Zone-redundant storage.
      - value: Standard_GRS
        name: StandardGeoRedundancy
      - value: Standard_RAGRS
      - value: Premium_LRS
```

### Single value enum

- `x-ms-enum.modelAsString=true` **(Default)**

Will be treated as an extensible enum(Same as with multi value enum)

- `x-ms-enum.modelAsString=false`

- If the **single value** enum is a **required** model property or a **required** then it will be treated as a Constant behind the scene. The SDK should automatically set that value and the parameter will not be on the operation signature.
- If the **single value** enum is an **optional** model property or an **optional** parameter, it will be treated as an optional parameter where the enum value can be set or not to that unique option.

## x-ms-parameter-grouping

By default operation parameters are generated in the client as method arguments. This behavior can sometimes be undesirable when the number of parameters is high. `x-ms-parameter-grouping` extension is used to group multiple primitive parameters into a composite type to improve the API.
{'fraction_non_alphanumeric': 0.14752224671401748, 'fraction_numerical': 0.004081965874765287, 'mean_word_length': 1.8941523922031895, 'pattern_counts': {'":': 22, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 26, 'lorem ipsum': 0, 'www.': 2, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 136, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '2195058', 'n_tokens_mistral': 5565, 'n_tokens_neox': 5362, 'n_words': 2182}