Azure
/
autorest
зеркало из https://github.com/Azure/autorest.git
1
0
Форкнуть 0
Код Задачи Пакеты Проекты Релизы Вики Активность

Fix: reference to master branch -> rename to main (#4146) 

* Confiugre rush to use main as default branch

* Remove master refs

* Remove master refs

* Remove master refs
This commit is contained in:
Timothee Guerin 2021-05-24 13:31:36 -07:00 коммит произвёл GitHub
Родитель fdd31b5233
Коммит 6caa31c18f
Не найден ключ, соответствующий данной подписи
Идентификатор ключа GPG: 4AEE18F83AFDEB23
29 изменённых файлов: 342 добавлений и 253 удалений
Показать статистику Скачать Patch файл Скачать Diff файл Показать все файлы Свернуть все файлы

8
.github/ISSUE_TEMPLATE/question.md поставляемый
Просмотреть файл

@ -1,12 +1,12 @@
---
name: Question
about: Ask a question about autorest
title: ''
title: ""
labels: question
assignees: ''
assignees: ""
---
Before asking the question:
- [ ] have you checked the documentation in the [docs folder(https://github.com/Azure/autorest/tree/master/docs) and couldn't find the information there
- [ ] have you checked the documentation in the [docs folder(https://github.com/Azure/autorest/tree/main/docs) and couldn't find the information there
- [ ] have you checked existing issues for a similar question?

6
docs/developer/readme.md
Просмотреть файл

@ -7,6 +7,6 @@ Current docs are [here][writing_an_extension], more incoming
<!-- LINKS -->
[writing_an_extension]: https://github.com/Azure/autorest/blob/master/docs/developer/writing-an-extension.md
[conventions]: https://github.com/Azure/autorest/blob/master/docs/developer/conventions.md
[feature-status]: https://github.com/Azure/autorest/blob/master/docs/developer/feature-status-tracking.md
[writing_an_extension]: https://github.com/Azure/autorest/blob/main/docs/developer/writing-an-extension.md
[conventions]: https://github.com/Azure/autorest/blob/main/docs/developer/conventions.md
[feature-status]: https://github.com/Azure/autorest/blob/main/docs/developer/feature-status-tracking.md

273
docs/extensions/readme.md
Просмотреть файл

@ -1,51 +1,55 @@
# 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.
- [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
- [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
| 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": {
@ -57,6 +61,7 @@ Field Name | Type | Description
```
## 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)
@ -65,6 +70,7 @@ By default, `path` parameters will be URL-encoded automatically. This is a good
`true|false`
**Example**:
```json5
"parameters": [
{
@ -78,6 +84,7 @@ By default, `path` parameters will be URL-encoded automatically. This is a good
```
## 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.
@ -86,57 +93,61 @@ In C# and Java, an enum type is generated and is declared as the type of the rel
**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.
| 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
- 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
- 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.
**Parent element**: [Parameter Object](https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md#parameterObject)
**Schema**:
Field Name | Type | Description
---|:---:|---
name | `string` | When set, specifies the name for the composite type.
postfix | `string` | Alternative to `name` parameter. If specified the name of the composite type will be generated as follows `{MethodGroup}{Method}{Postfix}`.
| Field Name | Type | Description |
| ---------- | :------: | ------------------------------------------------------------------------------------------------------------------------------------------- |
| name | `string` | When set, specifies the name for the composite type. |
| postfix | `string` | Alternative to `name` parameter. If specified the name of the composite type will be generated as follows `{MethodGroup}{Method}{Postfix}`. |
If none of the parameters are set the name of the composite type is generated as follows `{MethodGroup}{Method}Parameters`.
**Example**:
```json5
"/some/{pathParam1}/{pathParam2}": {
"operationId": "Update",
@ -172,6 +183,7 @@ If none of the parameters are set the name of the composite type is generated as
}
}
```
Above OpenAPI definition will produce a type CustomParameterGroup with 3 properties (if applicable in the generator language).
## x-ms-parameter-location
@ -180,10 +192,12 @@ By default Autorest processes global parameters as properties on the client. For
`"x-ms-parameter-location": "method"` and resourceGroupName will not be a client property.
Note:
- Valid values for this extension are: **"client", "method"**.
- **This extension can only be applied on global parameters. If this is applied on any parameter in an operation then it will be ignored.**
**Example:**
```json5
{
"swagger": "2.0",
@ -258,10 +272,13 @@ Note:
- After using the `"x-ms-parameter-location": "method"` extension the generated client will have a method that looks like this:
- Notice that `resourceGroupName` is the method parameter and not a client property
```csharp
public static StorageAccount Create(this IStorageAccountsOperations operations, string resourceGroupName, string accountName, StorageAccountCreateParameters parameters);
```
- The client constructor looks like this:
```csharp
public partial class StorageManagementClient : ServiceClient<StorageManagementClient>, IStorageManagementClient, IAzureClient
{
@ -296,19 +313,20 @@ public partial class StorageManagementClient : ServiceClient<StorageManagementCl
}
}
```
## x-ms-paths
OpenAPI 2.0 has a built-in limitation on paths. Only one operation can be mapped to a path and http method. There are some APIs, however, where multiple distinct operations are mapped to the same path and same http method. For example `GET /mypath/query-drive?op=file` and `GET /mypath/query-drive?op=folder` may return two different model types (stream in the first example and JSON model representing Folder in the second). Since OpenAPI does not treat query parameters as part of the path the above 2 operations may not co-exist in the standard "paths" element.
To overcome this limitation an "x-ms-paths" extension was introduced parallel to "paths". URLs under "x-ms-paths" are allowed to have query parameters for disambiguation, however they are not actually used.
**Parent element**: [Swagger Object](https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md#swaggerObject)
**Schema**:
The `x-ms-paths` extension has the same schema as [Paths Object](https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md#pathsObject) with exception that [Path Item Object](https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md#pathItemObject) can have query parameters.
**Example**:
```yaml
paths:
"/pets":
@ -341,6 +359,7 @@ By using the 'x-ms-client-name' extension, a name can be defined for use specifi
It can be used for query parameters and header parameters, as well as properties of schemas.
**Parameter Example**:
```json5
"parameters": {
"ApiVersionParameter": {
@ -366,6 +385,7 @@ It can be used for query parameters and header parameters, as well as properties
```
**Property Example**:
```json5
{
"definitions": {
@ -382,6 +402,7 @@ It can be used for query parameters and header parameters, as well as properties
```
## x-ms-external
To allow generated clients to share models via shared libraries an `x-ms-external` extension was introduced. When a [Schema Object](https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md#schema-object) contains this extensions it's definition will be excluded from generated library. Note that in strongly typed languages the code will not compile unless the assembly containing the type is referenced with the project/library.
**Parent element**: [Schema Object](https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md#schema-object)
@ -390,6 +411,7 @@ To allow generated clients to share models via shared libraries an `x-ms-externa
`true|false`
**Example**:
```json5
{
"definitions": {
@ -405,14 +427,16 @@ To allow generated clients to share models via shared libraries an `x-ms-externa
```
## x-ms-discriminator-value
Swagger 2.0 specification requires that when used, the value of `discriminator` field MUST match the name of the schema or any schema that inherits it. To overcome this limitation `x-ms-discriminator-value` extension was introduced.
**Schema**:
`string` - the expected value of the `discriminator` field on the wire.
**Parent element**: [Schema Object](https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md#schemaObject)
**Parent element**: [Schema Object](https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md#schemaObject)
**Example**:
```json5
"definitions": {
"SqlDefinition": {
@ -427,22 +451,26 @@ Swagger 2.0 specification requires that when used, the value of `discriminator`
```
## x-ms-client-flatten
This extension allows to flatten deeply nested payloads into a more user friendly object. For example a payload that looks like this on the wire:
```json5
{
"template": {
"name": "some name",
"properties": {
"prop1": "value1",
"prop2": "value2",
"url": {
"value": "http://myurl"
}
}
}
template: {
name: "some name",
properties: {
prop1: "value1",
prop2: "value2",
url: {
value: "http://myurl",
},
},
},
}
```
can be transformed into the following client model:
```cs
public class Template
{
@ -452,7 +480,9 @@ public class Template
public string UrlValue {get;set;}
}
```
by using the following OpenAPI definition:
```json5
"definitions": {
"template": {
@ -468,11 +498,15 @@ by using the following OpenAPI definition:
}
}
```
It's also possible to flatten body parameters so that the method will look like this:
```cs
client.DeployTemplate("some name", "value1", "value2", "http://myurl");
```
by using the following OpenAPI definition:
```json5
"post": {
"operationId": "DeployTemplate",
@ -495,6 +529,7 @@ by using the following OpenAPI definition:
`true|false`
**Example**:
```json5
"definitions": {
"template": {
@ -510,7 +545,9 @@ by using the following OpenAPI definition:
}
}
```
and
```json5
"post": {
"operationId": "DeployTemplate",
@ -528,23 +565,25 @@ and
```
## x-ms-parameterized-host
When used, replaces the standard OpenAPI "host" attribute with a host that contains variables to be replaced as part of method execution or client construction, very similar to how path parameters work.
**Parent element**: [Swagger Object](https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md#swagger-object)
**Parent element**: [Swagger Object](https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md#swagger-object)
**Schema**:
Field Name | Type | Description
---|:---:|---
hostTemplate | `string` | **Required**. Specifies the parameterized template for the host.
useSchemePrefix | `boolean` | **Optional, Default: true**. Specifies whether to prepend the default scheme a.k.a protocol to the base uri of client.
positionInOperation | `string` | **Optional, Default: first**. Specifies whether the list of parameters will appear in the beginning or in the end, in the method signature for every operation. The order within the parameters provided in the below mentioned array will be preserved. Either the array of parameters will be prepended or appended, based on the value provided over here. Valid values are **"first", "last"**. Every method/operation in any programming language has parameters categorized into two buckets **"required"** and **"optional"**. It is natural for optional parameters to appear in the end in a method signature. **This aspect will be preserved, while prepending(first) or appending(last) hostTemplate parameters .**
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.
| Field Name | Type | Description |
| ------------------- | :--------------------------------------------------------------------------------------------------------------------: | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| hostTemplate | `string` | **Required**. Specifies the parameterized template for the host. |
| useSchemePrefix | `boolean` | **Optional, Default: true**. Specifies whether to prepend the default scheme a.k.a protocol to the base uri of client. |
| positionInOperation | `string` | **Optional, Default: first**. Specifies whether the list of parameters will appear in the beginning or in the end, in the method signature for every operation. The order within the parameters provided in the below mentioned array will be preserved. Either the array of parameters will be prepended or appended, based on the value provided over here. Valid values are **"first", "last"**. Every method/operation in any programming language has parameters categorized into two buckets **"required"** and **"optional"**. It is natural for optional parameters to appear in the end in a method signature. **This aspect will be preserved, while prepending(first) or appending(last) hostTemplate parameters .** |
| 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.
- 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.
- 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.
```json5
"x-ms-parameterized-host": {
@ -575,8 +614,10 @@ parameters | [Array of Parameter Objects](https://github.com/OAI/OpenAPI-Specifi
"description": "Gets the DNS suffix used as the base for all Azure Data Lake Analytics Job service requests."
}
```
- 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 "useSchemePrefix" is set to false.
- 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 "useSchemePrefix" is set to false.
```json5
"x-ms-parameterized-host": {
"hostTemplate": "{accountName}.mystaticsuffix.com",
@ -596,17 +637,19 @@ parameters | [Array of Parameter Objects](https://github.com/OAI/OpenAPI-Specifi
```
## x-ms-mutability
This extension offers insight to Autorest on how to generate code (mutability of the property of the model classes being generated). It doesn't alter the modeling of the actual payload that is sent on the wire.
It is an array of strings with three possible values. The array cannot have repeatable values. Valid values are: **"create", "read", "update"**.
Field Name | Description
---|:---
**create** | Indicates that the value of the property can be set while creating/initializing/constructing the object
**read** | Indicates that the value of the property can be read
**update** | Indicates that value of the property can be updated anytime(even after the object is created)
| Field Name | Description |
| ---------- | :------------------------------------------------------------------------------------------------------ |
| **create** | Indicates that the value of the property can be set while creating/initializing/constructing the object |
| **read** | Indicates that the value of the property can be read |
| **update** | Indicates that value of the property can be updated anytime(even after the object is created) |
### Rules:
- When the extension is applied with all the three values; `"x-ms-mutability": ["create", "read", "update"]` (order of the values is not important) **OR** when this extension is not applied on a model property; it has the same effect in both the cases. Thus applying this extension with all the three values on all the settable properties is not required. This will ensure the spec is visibly cleaner.
- When a property is modeled as `"readonly": true` then,
- if the x-ms-mutability extension is applied then it can **only have "read" value in the array**.
@ -618,7 +661,9 @@ Field Name | Description
- When this extension is applied on a collection (array, dictionary) then this will have effects on the mutability (adding/removing elements) of the collection. Mutability of the collection cannot be applied on its elements. The mutability of the element will be governed based on the mutability defined in the element's definition.
Examples:
- Mutability on a model definition
```json5
"definitions": {
"Resource": {
@ -660,7 +705,9 @@ Examples:
}
}
```
- Mutability of the object property; which is a collection of items
```json5
"definitions": {
"ResourceCollection": {
@ -684,6 +731,7 @@ Examples:
```
## x-ms-examples
Describes the format for specifying examples for request and response of an operation in an OpenAPI definition. It is a **dictionary** of different variations of the examples for a given operation.
More information about this extension can be found [here](https://github.com/Azure/azure-rest-api-specs/tree/master/documentation/x-ms-examples.md).
@ -691,14 +739,16 @@ More information about this extension can be found [here](https://github.com/Azu
# Microsoft Azure Extensions (available in most generators only when using `--azure-arm`)
## x-ms-odata
When present the `x-ms-odata` extensions indicates the operation includes one or more [OData](http://www.odata.org/) query parameters. These parameters include `$filter`, `$top`, `$orderby`, `$skip`, and `$expand`. In some languages the generated method will expose these parameters as strongly types OData type.
When present the `x-ms-odata` extensions indicates the operation includes one or more [OData](http://www.odata.org/) query parameters. These parameters include `$filter`, `$top`, `$orderby`, `$skip`, and `$expand`. In some languages the generated method will expose these parameters as strongly types OData type.
**Schema**:
[`ref`](https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md#referenceObject) to the definition that describes object used in filter.
**Parent element**: [Operation Object](https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md#operationObject)
**Parent element**: [Operation Object](https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md#operationObject)
**Example**:
```json5
"paths": {
"/subscriptions/resource": {
@ -710,6 +760,7 @@ When present the `x-ms-odata` extensions indicates the operation includes one or
```
## x-ms-error-response
Indicates whether the response status code should be treated as an error response or not.
**Parent element**: [Response Object](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#response-object)
@ -718,6 +769,7 @@ Indicates whether the response status code should be treated as an error respons
`true|false`
**Example**:
```json5
. . .
"responses": {
@ -759,6 +811,7 @@ Indicates whether the response status code should be treated as an error respons
```
## x-ms-text
Swagger spec doesn't allow dev to model this XML structure: `<title language="text">the title</title>`
This is well known issue: https://github.com/OAI/OpenAPI-Specification/issues/630
@ -772,6 +825,7 @@ Note: The extension is not tight to this particular scenario (you could model an
`true|false`
**Example**:
```json5
. . .
"properties":{
@ -795,6 +849,7 @@ Note: The extension is not tight to this particular scenario (you could model an
```
## x-ms-client-default
Set the default value for a property or a parameter.
With this extension, you can set a default value for a property or parameter that is independent of how the property / parameter's schema is handling a default. This is different than the `default` value
@ -806,6 +861,7 @@ you can speciy
`string`, `integer`, `long`, `float`, `double`, `boolean` - the default value for the property / parameter
**Parameter Example**:
```json5
. . .
"parameters": [
@ -829,6 +885,7 @@ you can speciy
```
**Property Example**:
```json5
. . .
"properties": {
@ -849,23 +906,25 @@ you can speciy
```
## x-ms-pageable
The REST API guidelines define a common pattern for paging through lists of data. The operation response is modeled in OpenAPI as a list of items (a "page") and a link to the next page, effectively resembling a singly linked list. Tag the operation as `x-ms-pageable` and the generated code will include methods for navigating between pages.
**Note:** The request to get the nextPage will always be a `GET` request
**Schema**:
Field Name | Type | Description
---|:---:|---
itemName | `string` | Optional (default: `value`). Specifies the name of the property that provides the collection of pageable items.
nextLinkName| `string` | Required. Specifies the name of the property that provides the next link (common: `nextLink`). If the model does not have a next link property then specify `null`. This is useful for services that return an object that has an array referenced by `itemName`. The object is then flattened in a way that the array is *directly* returned, no paging is used. This provides a better client side API to the end user.
operationName | `string` | Optional (default: `<operationName>Next`). Specifies the name of the operation for retrieving the next page.
| Field Name | Type | Description |
| ------------- | :------: | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| itemName | `string` | Optional (default: `value`). Specifies the name of the property that provides the collection of pageable items. |
| nextLinkName | `string` | Required. Specifies the name of the property that provides the next link (common: `nextLink`). If the model does not have a next link property then specify `null`. This is useful for services that return an object that has an array referenced by `itemName`. The object is then flattened in a way that the array is _directly_ returned, no paging is used. This provides a better client side API to the end user. |
| operationName | `string` | Optional (default: `<operationName>Next`). Specifies the name of the operation for retrieving the next page. |
**Parent element**: [Operation Object](https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md#operationObject)
**Parent element**: [Operation Object](https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md#operationObject)
**Example 1: Canonical**
Basic use of `x-ms-pageable`:
```YAML
swagger: '2.0'
info:
@ -897,7 +956,9 @@ definitions:
nextLink: # next page URL (referred to by "nextLinkName")
type: string
```
Generated signatures:
```C#
IPage<int?> List(ISimpleAPIClient operations);
Task<IPage<int?>> ListAsync(ISimpleAPIClient operations, CancellationToken cancellationToken);
@ -905,11 +966,12 @@ IPage<int?> ListNext(ISimpleAPIClient operations, string nextPageLink);
Task<IPage<int?>> ListNextAsync(ISimpleAPIClient operations, string nextPageLink, CancellationToken cancellationToken);
```
- Swagger example: [pollingPaging.json](https://github.com/Azure/autorest/blob/master/docs/openapi/examples/pollingPaging.json#L53)
- Swagger example: [pollingPaging.json](https://github.com/Azure/autorest/blob/main/docs/openapi/examples/pollingPaging.json#L53)
**Example 2: Customized**
Customizing code generation:
```YAML
swagger: '2.0'
info:
@ -943,7 +1005,9 @@ definitions:
nextIntegersUrl: # next page URL (referred to by "nextLinkName")
type: string
```
Generated signatures:
```C#
IPage<int?> List(ISimpleAPIClient operations);
Task<IPage<int?>> ListAsync(ISimpleAPIClient operations, CancellationToken cancellationToken);
@ -954,6 +1018,7 @@ Task<IPage<int?>> ListMoreAsync(ISimpleAPIClient operations, string nextPageLink
**Example 3: Single page result**
Providing a better user experience for single page response models:
```YAML
swagger: '2.0'
info:
@ -984,16 +1049,20 @@ definitions:
items:
type: integer
```
Generated signatures:
```C#
IEnumerable<int?> List(ISimpleAPIClient operations);
Task<IEnumerable<int?>> ListAsync(ISimpleAPIClient operations, CancellationToken cancellationToken);
```
## x-ms-long-running-operation
Some requests like creating/deleting a resource cannot be carried out immediately. In such a situation, the server sends a 201 (Created) or 202 (Accepted) and provides a link to monitor the status of the request. When such an operation is marked with extension `"x-ms-long-running-operation": true`, in OpenAPI, the generated code will know how to fetch the link to monitor the status. It will keep on polling at regular intervals till the request reaches one of the terminal states: Succeeded, Failed, or Canceled.
### x-ms-long-running-operation-options
When `x-ms-long-running-operation` is specified, there should also be a `x-ms-long-running-operation-options` specified.
See [Azure RPC Spec](https://github.com/Azure/azure-resource-manager-rpc/blob/master/v1.0/Addendum.md#asynchronous-operations) for asynchronous operation notes.
@ -1002,15 +1071,17 @@ See [Azure RPC Spec](https://github.com/Azure/azure-resource-manager-rpc/blob/ma
Field Name | Type | Description
---|:---:|---
final-state-via | `string` - one of `azure-async-operation` or `location` or `original-uri` | `final-state-via` SHOULD BE one of
- `azure-async-operation` - (default if not specified) poll until terminal state, the final response will be available at the uri pointed to by the header `Azure-AsyncOperation`
- `location` - poll until terminal state, the final response will be available at the uri pointed to by the header `Location`
- `original-uri` - poll until terminal state, the final response will be available via GET at the original resource URI. Very common for PUT operations.
- `azure-async-operation` - (default if not specified) poll until terminal state, the final response will be available at the uri pointed to by the header `Azure-AsyncOperation`
- `location` - poll until terminal state, the final response will be available at the uri pointed to by the header `Location`
- `original-uri` - poll until terminal state, the final response will be available via GET at the original resource URI. Very common for PUT operations.
It will keep on polling at regular intervals till the request reaches one of the terminal states: Succeeded, Failed, or Canceled.
**Parent element**: [Operation Object](https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md#operationObject)
**Parent element**: [Operation Object](https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md#operationObject)
**Example**:
```json5
"paths": {
"/products/{name}": {
@ -1026,17 +1097,19 @@ It will keep on polling at regular intervals till the request reaches one of the
}
```
- Swagger example: [pollingPaging.json](https://github.com/Azure/autorest/blob/master/docs/openapi/examples/pollingPaging.json#L19)
- Swagger example: [pollingPaging.json](https://github.com/Azure/autorest/blob/main/docs/openapi/examples/pollingPaging.json#L19)
## x-ms-azure-resource
Resource types as defined by the [Resource Manager API](https://msdn.microsoft.com/en-us/library/azure/dn790568.aspx) are tagged by using a `x-ms-azure-resource` extension.
**Parent element**: [Schema Object](https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md#schemaObject)
**Parent element**: [Schema Object](https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md#schemaObject)
**Schema**:
`true|false`
**Example**:
```json5
"Resource": {
"x-ms-azure-resource": true,
@ -1051,14 +1124,16 @@ Resource types as defined by the [Resource Manager API](https://msdn.microsoft.c
```
## x-ms-request-id
When set, allows to overwrite the `x-ms-request-id` response header (default is x-ms-request-id).
**Parent element**: [Operation Object](https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md#operationObject)
**Parent element**: [Operation Object](https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md#operationObject)
**Schema**:
`string` - the name of the request id header to use when setting Response.RequestId property.
**Example**:
```json5
"paths": {
"/products/{name}": {
@ -1071,14 +1146,16 @@ When set, allows to overwrite the `x-ms-request-id` response header (default is
```
## x-ms-client-request-id
When set, specifies the header parameter to be used instead of `x-ms-client-request-id` (default is x-ms-client-request-id).
**Parent element**: [Header Parameter Object](https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md#parameterObject)
**Parent element**: [Header Parameter Object](https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md#parameterObject)
**Schema**:
`string` - the name of the client request id header to use when setting sending request.
**Example**:
```json5
"paths": {
"/products/{name}": {
@ -1097,12 +1174,14 @@ When set, specifies the header parameter to be used instead of `x-ms-client-requ
```
## x-nullable
Set `"x-nullable": true` on a schema to indicate that a `null` is a legal value. By default, a `null` value should be disallowed when forming a request and rejected during payload deserialization.
Set `"x-nullable": true` on a schema to indicate that a `null` is a legal value. By default, a `null` value should be disallowed when forming a request and rejected during payload deserialization.
For arrays, sending/receiving a `null` array entry is not supported and should result in an error.
**Example**:
An operation that returns a scalar value or null.
```json
"responses": {
"200": {
@ -1117,6 +1196,7 @@ An operation that returns a scalar value or null.
**Example**:
An operation that returns an object or null.
```json
"responses": {
"200": {
@ -1133,6 +1213,7 @@ An operation that returns an object or null.
**Example**:
A dictionary where a key's value can be null.
```json
{
"name": "arrayBody",
@ -1153,6 +1234,7 @@ A dictionary where a key's value can be null.
**Example**:
An object with an optional property.
```json
"Widget": {
"type": "object",
@ -1171,6 +1253,7 @@ An object with an optional property.
```
## x-ms-header-collection-prefix
Handle collections of arbitrary headers by distinguishing them with a specified prefix. Has different behavior if it refers to a request header or a response header:
- Request header: All keys in the request headers will be prefixed with the prefix value before being sent to the service.

2
docs/generate/built-in-directives.md
Просмотреть файл

@ -2,7 +2,7 @@
Autorest provides a set of built-in directives for common scenarios to simplify things.
Those directives are defined [here](https://github.com/Azure/autorest/blob/master/packages/libs/configuration/resources/directives.md)
Those directives are defined [here](https://github.com/Azure/autorest/blob/main/packages/libs/configuration/resources/directives.md)
## Selection

6
docs/generate/directives.md
Просмотреть файл

@ -27,7 +27,7 @@ Directives consist of three parts:
- A `property` can be filtered by:
- its location within its parent object
- **Transform**: denoted by the field `transform`, the actions we would like to be applied on the specified objects. The list of available variables and functions can be found in [eval.ts](https://github.com/Azure/autorest/blob/master/packages/extensions/core/src/lib/plugins/transformer/eval.ts)
- **Transform**: denoted by the field `transform`, the actions we would like to be applied on the specified objects. The list of available variables and functions can be found in [eval.ts](https://github.com/Azure/autorest/blob/main/packages/extensions/core/src/lib/plugins/transformer/eval.ts)
## Built-in Directives
@ -279,5 +279,5 @@ For language-specific directives, see the ones for:
[paths]: https://swagger.io/docs/specification/paths-and-operations/
[parameters]: https://swagger.io/docs/specification/describing-parameters/
[components]: https://swagger.io/docs/specification/components/
[x_ms_client_name]: https://github.com/Azure/autorest/blob/master/docs/extensions/readme.md#x-ms-client-name
[x_ms_enum]: https://github.com/Azure/autorest/blob/master/docs/extensions/readme.md#x-ms-enum
[x_ms_client_name]: https://github.com/Azure/autorest/blob/main/docs/extensions/readme.md#x-ms-client-name
[x_ms_enum]: https://github.com/Azure/autorest/blob/main/docs/extensions/readme.md#x-ms-enum

193
docs/generate/flags.md
Просмотреть файл

@ -1,27 +1,29 @@
# <img align="center" src="../images/logo.png"> Index of AutoRest Flags
# <img align="center" src="../images/logo.png"> Index of AutoRest Flags
## Shared Flags
| Flag | Description | Python | .NET | Java | TS | Go
|------------------|-------------|-------------|-------------|-------------|-------------|-------------
| `--input-file=FILENAME` | Adds the given file to the list of input files for generation process | x | x | x | x | x
|`--output-folder=DIRECTORY`|The location for generated files. If not specified, uses `./generated` as the default| x | x | x | x | x
|`--clear-output-folder`|Clear all contents from our output folder before outputting your newly generated code into that folder. Defaults to `false`.| x | x | x | x | x
|`--project-folder=DIRECTORY`|Use this flag if you have a project folder that will contain both generated code and existing code you would like to persist. You can then define the output folder relative to this project folder, i.e. `output-folder: $(project-folder)/generated`.| x | x | x | x | x
|`--add-credential`|If specified, the generated client will require a credential to make network calls. See [our language docs][client] for information on how to authenticate to our generated clients. Forced to be `true` if `--azure-arm` is set, otherwise defaults to `false`.| x | No flag for `--add-credential`, will add credential param for a `TokenCredential` if `--azure-arm` is `true`. | No flag for `--add-credential`, gets whether to add credential from value of `--credential-types`. Defaults to false.| Is called `--add-credentials`. Defaults to false. | No flag, looks in `authenticationRequired` field in the swagger. Does not automatically set to true in azure-arm.
|`--credential-scopes=VALUE(S)`|Specify the scopes over which the credential functions (see previous flag `--add-credential` for adding client credentials). This is tied with `BearerTokenCredentialPolicy`. If generating management plane code (see `--azure-arm` flag directly below), we default the scope to `'https://management.azure.com/.default'`. If not, we highly recommend you use this flag if `--add-credential` is specified. If you don't generate with scopes in this case, it forces your SDK users to pass credential scopes themselves when calling your code. You can pass multiple values in using CSV format.| x | No flag for credential scopes. Currently only sets `TokenCredential` in mgmt mode. In mgmt mode's case, the credential scope is forced to `{endpoint}/.default`. In mgmt mode, this endpoint (which is gotten from the swagger), is `https://management.azure.com`| Currently doesn't default to ARM scope in mgmt mode | | `--credential-scope`
|`--license-header=LICENSE_HEADER`|Specify the type of license header for your files. Common values include `MICROSOFT_MIT_NO_VERSION` and `MICROSOFT_MIT_NO_CODEGEN` TODO: list of all possible values and default| x | x | x | x | x
|`--namespace=NAMESPACE`|Sets the namespace to use for the generated code| x | x | x | |
|`--tag=VALUE`|Preferred way to have conditional configurations. I.e., in my configuration file, I can set the `input-file` equal to different values depending on the `VALUE` passed through the `tag` flag. See our [Adding Tags When Generating][adding_tags_when_generating] section for more information|
|`--azure-arm`|generates control plane (Azure Resource Manager) code. Use this if you're generate SDKs for people to manage their Azure resources. See our [mgmt plane section][mgmt_plane_section] for more info. Defaults to `false`.| x | x | x | x | Uses flag `--openapi-type=arm` to specify
|`--head-as-boolean`|With this flag, HEAD calls to non-existent resources (404) will not raise an error. Instead, if the resource exists, we return `true`, else `false`. Forced to be `true` if `--azure-arm` is set, otherwise defaults to `false`.| x | x ||| Go default is always `false`.
|`--title=NAME`|Override the service client's name listed in the swagger under `title`.| x | x | x | x | x
|`--description=DESCRIPTION`|Override the service client's description listed in the swagger under the top level `description`.| x | x | x | x | x
|`--client-side-validation`|Whether you want the SDK to perform validation on inputs and outputs, based on swagger information. Recommended to be `false` for track 2 code, since we want the network to validate instead. Defaults to `false`.| x | x | calls it `--client-side-validations` | | x
|`--package-name=NAME`|The name of your package. This is the name your package will be published under.| x | | |x |
|`--package-version=VERSION`|The semantic versioning of your generated SDK (i.e., `1.0.0`). Not to be confused with the version of the service you're creating an SDK for. If no version is specified, AutoRest will not create a new version file. Generally not necessary if you are going to wrap the generated code before exposing to users.| Needs to be specified if `--basic-setup-py` is specified. | Currently can't generate version for track 2|Default is `1.0.0-beta.1`. Only available in `fluent` mode.|Currently can't set version for track 2| Defaults to `1.0.0`|
|`--trace`|Whether to natively support tracing libraries, such OpenCensus or OpenTelemetry. See this [tracing quickstart][tracing_quickstart] for an overview. Defaults to `false`.| x | | | x|
| Flag | Description | Python | .NET | Java | TS | Go |
| --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
| `--input-file=FILENAME` | Adds the given file to the list of input files for generation process | x | x | x | x | x |
| `--output-folder=DIRECTORY` | The location for generated files. If not specified, uses `./generated` as the default | x | x | x | x | x |
| `--clear-output-folder` | Clear all contents from our output folder before outputting your newly generated code into that folder. Defaults to `false`. | x | x | x | x | x |
| `--project-folder=DIRECTORY` | Use this flag if you have a project folder that will contain both generated code and existing code you would like to persist. You can then define the output folder relative to this project folder, i.e. `output-folder: $(project-folder)/generated`. | x | x | x | x | x |
| `--add-credential` | If specified, the generated client will require a credential to make network calls. See [our language docs][client] for information on how to authenticate to our generated clients. Forced to be `true` if `--azure-arm` is set, otherwise defaults to `false`. | x | No flag for `--add-credential`, will add credential param for a `TokenCredential` if `--azure-arm` is `true`. | No flag for `--add-credential`, gets whether to add credential from value of `--credential-types`. Defaults to false. | Is called `--add-credentials`. Defaults to false. | No flag, looks in `authenticationRequired` field in the swagger. Does not automatically set to true in azure-arm. |
| `--credential-scopes=VALUE(S)` | Specify the scopes over which the credential functions (see previous flag `--add-credential` for adding client credentials). This is tied with `BearerTokenCredentialPolicy`. If generating management plane code (see `--azure-arm` flag directly below), we default the scope to `'https://management.azure.com/.default'`. If not, we highly recommend you use this flag if `--add-credential` is specified. If you don't generate with scopes in this case, it forces your SDK users to pass credential scopes themselves when calling your code. You can pass multiple values in using CSV format. | x | No flag for credential scopes. Currently only sets `TokenCredential` in mgmt mode. In mgmt mode's case, the credential scope is forced to `{endpoint}/.default`. In mgmt mode, this endpoint (which is gotten from the swagger), is `https://management.azure.com` | Currently doesn't default to ARM scope in mgmt mode | | `--credential-scope` |
| `--license-header=LICENSE_HEADER` | Specify the type of license header for your files. Common values include `MICROSOFT_MIT_NO_VERSION` and `MICROSOFT_MIT_NO_CODEGEN` TODO: list of all possible values and default | x | x | x | x | x |
| `--namespace=NAMESPACE` | Sets the namespace to use for the generated code | x | x | x | |
| `--tag=VALUE` | Preferred way to have conditional configurations. I.e., in my configuration file, I can set the `input-file` equal to different values depending on the `VALUE` passed through the `tag` flag. See our [Adding Tags When Generating][adding_tags_when_generating] section for more information |
| `--azure-arm` | generates control plane (Azure Resource Manager) code. Use this if you're generate SDKs for people to manage their Azure resources. See our [mgmt plane section][mgmt_plane_section] for more info. Defaults to `false`. | x | x | x | x | Uses flag `--openapi-type=arm` to specify |
| `--head-as-boolean` | With this flag, HEAD calls to non-existent resources (404) will not raise an error. Instead, if the resource exists, we return `true`, else `false`. Forced to be `true` if `--azure-arm` is set, otherwise defaults to `false`. | x | x | | | Go default is always `false`. |
| `--title=NAME` | Override the service client's name listed in the swagger under `title`. | x | x | x | x | x |
| `--description=DESCRIPTION` | Override the service client's description listed in the swagger under the top level `description`. | x | x | x | x | x |
| `--client-side-validation` | Whether you want the SDK to perform validation on inputs and outputs, based on swagger information. Recommended to be `false` for track 2 code, since we want the network to validate instead. Defaults to `false`. | x | x | calls it `--client-side-validations` | | x |
| `--package-name=NAME` | The name of your package. This is the name your package will be published under. | x | | | x |
| `--package-version=VERSION` | The semantic versioning of your generated SDK (i.e., `1.0.0`). Not to be confused with the version of the service you're creating an SDK for. If no version is specified, AutoRest will not create a new version file. Generally not necessary if you are going to wrap the generated code before exposing to users. | Needs to be specified if `--basic-setup-py` is specified. | Currently can't generate version for track 2 | Default is `1.0.0-beta.1`. Only available in `fluent` mode. | Currently can't set version for track 2 | Defaults to `1.0.0` |
| `--trace` | Whether to natively support tracing libraries, such OpenCensus or OpenTelemetry. See this [tracing quickstart][tracing_quickstart] for an overview. Defaults to `false`. | x | | | x |
## Autorest flags
Those are flags that affect autorest only
| Flag | Description |
@ -29,106 +31,107 @@ Those are flags that affect autorest only
| `--output-converted-oai3` | If enabled and the input-files are `swager 2.0` this will output the resulting OpenAPI3.0 converted files to the `output-folder` |
| `--skip-semantics-validation` | Disable the semantic validator plugin. |
## Temporary flags
Those flags are temporary and will be removed in the future. Those flags are here to have a smoother rollout of certain feature.
| Flag | Description
|------------------|-------------
| `--mark-oai3-errors-as-warnings` | Mark OpenAPI3 validation(schema) error as warnings. (When removed OpenAPI3 validation errors will always fail the pipeline)
| Flag | Description |
| -------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| `--mark-oai3-errors-as-warnings` | Mark OpenAPI3 validation(schema) error as warnings. (When removed OpenAPI3 validation errors will always fail the pipeline) |
## Python Flags
| Flag | Description
|------------------|-------------
|`--python-sdks-folder=DIRECTORY`| The path to the root directory of your [`azure-sdk-for-python`][azure_sdk_for_python] clone. Be sure to note that we include `sdk` in the folder path.
|`--black`| Runs [black][black] formatting on your generated files. Defaults to `false`.
|`--basic-setup-py`|Whether to generate a build script for setuptools to package your SDK. See [here][setup_py] for more information about a `setup.py` file. Defaults to `false`, generally not suggested if you are going to wrap the generated code before exposing to users. Needs `--package-version` to be specified. Defaults to `false`.
|`--multiapi`|Whether to generate a multiapi client. See [our multiapi section][multiapi_section] for more information. Defaults to `false`.
|`--default-api=VALUE`|In the case of `--multiapi`, you can override the default service API version with this flag. If not specified, we use the latest GA service version as the default API.
|`--keep-version-file`|Whether you want to override the current version file in your package or not. Defaults to `false`.
|`--no-namespace-folders`|Specify if you don't want pkgutil-style namespace folders. See [here][namespace_folders] for more information on pkgutil namespace folders. Defaults to `false`.
|`--credential-default-policy-type=BearerTokenCredentialPolicy\|AzureKeyCredentialPolicy`|Specify the default credential policy (authentication policy) for your client. Use in conjunction with `--add-credential`. Currently only supports [`BearerTokenCredentialPolicy`][bearer_token_credential_policy] and [`AzureKeyCredentialPolicy`][azure_key_credential_policy]. Default value is `BearerTokenCredentialPolicy`. `--credential-scopes` is tied with `BearerTokenCredentialPolicy`, do not pass them in if you want `AzureKeyCredentialPolicy`.
|`--credential-key-header-name=NAME`|The name of the header which will pass the credential. Use if you have `--credential-default-policy-type` set to [`AzureKeyCredentialPolicy`][azure_key_credential_policy]. For example, if generating cognitive services code, you might use `--credential-key-header-name=Ocp-Apim-Subscription-Key`.
| Flag | Description |
| ---------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--python-sdks-folder=DIRECTORY` | The path to the root directory of your [`azure-sdk-for-python`][azure_sdk_for_python] clone. Be sure to note that we include `sdk` in the folder path. |
| `--black` | Runs [black][black] formatting on your generated files. Defaults to `false`. |
| `--basic-setup-py` | Whether to generate a build script for setuptools to package your SDK. See [here][setup_py] for more information about a `setup.py` file. Defaults to `false`, generally not suggested if you are going to wrap the generated code before exposing to users. Needs `--package-version` to be specified. Defaults to `false`. |
| `--multiapi` | Whether to generate a multiapi client. See [our multiapi section][multiapi_section] for more information. Defaults to `false`. |
| `--default-api=VALUE` | In the case of `--multiapi`, you can override the default service API version with this flag. If not specified, we use the latest GA service version as the default API. |
| `--keep-version-file` | Whether you want to override the current version file in your package or not. Defaults to `false`. |
| `--no-namespace-folders` | Specify if you don't want pkgutil-style namespace folders. See [here][namespace_folders] for more information on pkgutil namespace folders. Defaults to `false`. |
| `--credential-default-policy-type=BearerTokenCredentialPolicy\|AzureKeyCredentialPolicy` | Specify the default credential policy (authentication policy) for your client. Use in conjunction with `--add-credential`. Currently only supports [`BearerTokenCredentialPolicy`][bearer_token_credential_policy] and [`AzureKeyCredentialPolicy`][azure_key_credential_policy]. Default value is `BearerTokenCredentialPolicy`. `--credential-scopes` is tied with `BearerTokenCredentialPolicy`, do not pass them in if you want `AzureKeyCredentialPolicy`. |
| `--credential-key-header-name=NAME` | The name of the header which will pass the credential. Use if you have `--credential-default-policy-type` set to [`AzureKeyCredentialPolicy`][azure_key_credential_policy]. For example, if generating cognitive services code, you might use `--credential-key-header-name=Ocp-Apim-Subscription-Key`. |
## .NET Flags
| Flag | Description
|------------------|-------------
|`--library-name=NAME`|The name of your library. This is what will be displayed on NuGet.
|`--shared-source-folders=VALUE(S)`|Pass shared folder paths through here. Common values point to the [shared generator assets][shared_generator_assets] and [shared azure core assets][shared_azure_core_assets] in [autorest.csharp][autorest_csharp]
|`--public-clients`|Whether to have your client public. Defaults to `false`.
|`--model-namespace`|Whether to add a separate namespace of Models, more specifically adding `{value-from-namespace-flag}.Models`. Defaults to `true`.
| Flag | Description |
| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--library-name=NAME` | The name of your library. This is what will be displayed on NuGet. |
| `--shared-source-folders=VALUE(S)` | Pass shared folder paths through here. Common values point to the [shared generator assets][shared_generator_assets] and [shared azure core assets][shared_azure_core_assets] in [autorest.csharp][autorest_csharp] |
| `--public-clients` | Whether to have your client public. Defaults to `false`. |
| `--model-namespace` | Whether to add a separate namespace of Models, more specifically adding `{value-from-namespace-flag}.Models`. Defaults to `true`. |
## Java Flags
| Flag | Description
|------------------|-------------
|`--azure-libraries-for-java-folder=DIRECTORY` | The path to the root directory of your [`azure-sdk-for-java`][azure_sdk_for_java] clone. Be sure to note that we include `sdk` in the folder path.
|`--fluent=LITE\|PREMIUM`|Enables Java's fluent generator, generating a set of fluent Java interfaces for a guided and convenient user experience for the client library. Currently used by Azure management libraries. `LITE` for Fluent Lite; `PREMIUM` for Fluent Premium. Default is `PREMIUM` if provided as other values. See [the java docs][fluent_docs] for all of the Fluent specific flags.
|`--regenerate-pom`|Whether to regenerate the pom file in your project. See [here][pom] for more information on what a pom file is. Defaults to `false`.
|`--generate-client-as-impl`|Append "Impl" to the names of service clients and method groups and place them in the `implementation` sub-package. Defaults to `false`.
|`--generate-client-interfaces`|Generates interfaces for all the "Impl"s. Forces `--generate-client-as-impl` to `true`, and generates an interface for it as well. Defaults to `false`.
|`--generate-sync-async-clients`|Generates sync and async convenience layer clients for all the "Impl"s. Forces `--generate-client-as-impl` to `true`. Defaults to `false`.
|`--implementation-subpackage=NAME`|The sub-package that the Service client and Method Group client implementation classes will be put into. Defaults to `implementation`.
|`--models-subpackage=NAME`|The sub-package that Enums, Exceptions, and Model types will be put into. Defaults to `models`.
|`--add-context-parameter`|Indicates whether the [`com.azure.core.util.Context`][java_context] parameter should be included in generated proxy methods. Use if you want to pass arbitrary data (key-value pairs) to pipeline policies. Defaults to `false`.
|`--context-client-method-parameter`|Indicates whether the [`com.azure.core.util.Context`][java_context] parameter should also be included in generated client methods. Forces `--add-context-parameter` to `true`. Defaults to `false`.
|`--sync-methods=all\|essential\|none`|Specifies mode for generating sync wrappers. Supported values are <br>&nbsp;&nbsp;`essential` - generates only one sync returning body or header (default) <br>&nbsp;&nbsp;`all` - generates one sync method for each async method<br>&nbsp;&nbsp;`none` - does not generate any sync methods
|`--required-parameter-client-methods`|Indicates whether client method overloads with only required parameters should be generated. Defaults to `false`.
|`--custom-types-subpackage=VALUE`|The sub-package that the custom types should be generated in. The types that custom types reference, or inherit from will also be automatically moved to this sub-package. **Recommended usage**: You can set this value to `models` and set `--models-subpackage=implementation.models`to generate models to `implementation.models` by default and pick specific models to be public through `--custom-types`.
|`--custom-types=VALUE(S)`|Specifies a list of files to put in the package specified in `--custom-types-subpackage`. You can pass multiple values in using CSV format.
|`--client-type-prefix=PREFIX`|The prefix that will be added to each generated client type.
|`--model-override-setter-from-superclass`|Indicates whether to override the superclass setter method in model. Defaults to `false`.
|`--non-null-annotations`|Whether or not to add the `@NotNull` annotation to required parameters in client methods. Defaults to `false`.
|`--client-logger`|Whether the client should log by default. Defaults to `false`.
|`--required-fields-as-ctor-args`|Whether an object's required fields should be specified as arguments to its constructor. Defaults to `false`.
|`--service-interface-as-public`|Whether the service's interface should be set as public. Defaults to `false`.
|`--artifact-id`|The name of your project jar without its version. See [here][artifact_id] for more information about an artifact id.
|`--credential-types=TokenCredential\|AzureKeyCredential\|None`|The type of credential if `--add-credential` is specified. Defaults to `None`.
|`--customization-jar-path=FILEPATH`|Pass in the path to your .jar file that contains customizations to the output files. This will allow AutoRest to dynamically load the class you provide in `--customization-class`.
|`--customization-class=NAME`|Use in conjunction with `--customization-jar-path`. That flag tells AutoRest where to look for your custom class, while `--customization-class` tells AutoRest the name of your custom class.
| Flag | Description |
| -------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--azure-libraries-for-java-folder=DIRECTORY` | The path to the root directory of your [`azure-sdk-for-java`][azure_sdk_for_java] clone. Be sure to note that we include `sdk` in the folder path. |
| `--fluent=LITE\|PREMIUM` | Enables Java's fluent generator, generating a set of fluent Java interfaces for a guided and convenient user experience for the client library. Currently used by Azure management libraries. `LITE` for Fluent Lite; `PREMIUM` for Fluent Premium. Default is `PREMIUM` if provided as other values. See [the java docs][fluent_docs] for all of the Fluent specific flags. |
| `--regenerate-pom` | Whether to regenerate the pom file in your project. See [here][pom] for more information on what a pom file is. Defaults to `false`. |
| `--generate-client-as-impl` | Append "Impl" to the names of service clients and method groups and place them in the `implementation` sub-package. Defaults to `false`. |
| `--generate-client-interfaces` | Generates interfaces for all the "Impl"s. Forces `--generate-client-as-impl` to `true`, and generates an interface for it as well. Defaults to `false`. |
| `--generate-sync-async-clients` | Generates sync and async convenience layer clients for all the "Impl"s. Forces `--generate-client-as-impl` to `true`. Defaults to `false`. |
| `--implementation-subpackage=NAME` | The sub-package that the Service client and Method Group client implementation classes will be put into. Defaults to `implementation`. |
| `--models-subpackage=NAME` | The sub-package that Enums, Exceptions, and Model types will be put into. Defaults to `models`. |
| `--add-context-parameter` | Indicates whether the [`com.azure.core.util.Context`][java_context] parameter should be included in generated proxy methods. Use if you want to pass arbitrary data (key-value pairs) to pipeline policies. Defaults to `false`. |
| `--context-client-method-parameter` | Indicates whether the [`com.azure.core.util.Context`][java_context] parameter should also be included in generated client methods. Forces `--add-context-parameter` to `true`. Defaults to `false`. |
| `--sync-methods=all\|essential\|none` | Specifies mode for generating sync wrappers. Supported values are <br>&nbsp;&nbsp;`essential` - generates only one sync returning body or header (default) <br>&nbsp;&nbsp;`all` - generates one sync method for each async method<br>&nbsp;&nbsp;`none` - does not generate any sync methods |
| `--required-parameter-client-methods` | Indicates whether client method overloads with only required parameters should be generated. Defaults to `false`. |
| `--custom-types-subpackage=VALUE` | The sub-package that the custom types should be generated in. The types that custom types reference, or inherit from will also be automatically moved to this sub-package. **Recommended usage**: You can set this value to `models` and set `--models-subpackage=implementation.models`to generate models to `implementation.models` by default and pick specific models to be public through `--custom-types`. |
| `--custom-types=VALUE(S)` | Specifies a list of files to put in the package specified in `--custom-types-subpackage`. You can pass multiple values in using CSV format. |
| `--client-type-prefix=PREFIX` | The prefix that will be added to each generated client type. |
| `--model-override-setter-from-superclass` | Indicates whether to override the superclass setter method in model. Defaults to `false`. |
| `--non-null-annotations` | Whether or not to add the `@NotNull` annotation to required parameters in client methods. Defaults to `false`. |
| `--client-logger` | Whether the client should log by default. Defaults to `false`. |
| `--required-fields-as-ctor-args` | Whether an object's required fields should be specified as arguments to its constructor. Defaults to `false`. |
| `--service-interface-as-public` | Whether the service's interface should be set as public. Defaults to `false`. |
| `--artifact-id` | The name of your project jar without its version. See [here][artifact_id] for more information about an artifact id. |
| `--credential-types=TokenCredential\|AzureKeyCredential\|None` | The type of credential if `--add-credential` is specified. Defaults to `None`. |
| `--customization-jar-path=FILEPATH` | Pass in the path to your .jar file that contains customizations to the output files. This will allow AutoRest to dynamically load the class you provide in `--customization-class`. |
| `--customization-class=NAME` | Use in conjunction with `--customization-jar-path`. That flag tells AutoRest where to look for your custom class, while `--customization-class` tells AutoRest the name of your custom class. |
## TS Flags
| Flag | Description
|------------------|-------------
|`--source-code-folder-path=DIRECTORY`|Where to output the generated code inside the `output-folder`. Use in the scenario when you are going to write a convenience layer on top of the generated code. Defaults to `src`.| | || x|
|`--generate-metadata`|Whether to generate extra metadata in your package. For instance, generates a README file, license file etc if set to `true`. Defaults to `false`.
|`--tracing-spanprefix=SPAN_PREFIX`|If you are tracing (passing in flag `--trace`), and you want to overwrite the span prefix AutoRest assigns, use this flag.
|`--disable-async-iterators`|Whether to generate pageable methods as [AsyncIterators][ts_async_iterator]. Defaults to `true`.
| Flag | Description |
| ------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --- | --- | --- | --- |
| `--source-code-folder-path=DIRECTORY` | Where to output the generated code inside the `output-folder`. Use in the scenario when you are going to write a convenience layer on top of the generated code. Defaults to `src`. | | | | x |
| `--generate-metadata` | Whether to generate extra metadata in your package. For instance, generates a README file, license file etc if set to `true`. Defaults to `false`. |
| `--tracing-spanprefix=SPAN_PREFIX` | If you are tracing (passing in flag `--trace`), and you want to overwrite the span prefix AutoRest assigns, use this flag. |
| `--disable-async-iterators` | Whether to generate pageable methods as [AsyncIterators][ts_async_iterator]. Defaults to `true`. |
## Go flags
| Flag | Description
|------------------|-------------
|`--module=NAME`|The name of the module. This is the name your module will be published under.
|`--file-prefix=PREFIX`|Optional prefix to file names. For example, if you set your file prefix to "zzz", all generated code files will begin with "zzz".
|`--openapi-type=arm\|data-plane`|Specify if you want to generate `data-plane` code or `arm` code.
|`--armcore-connection`|If set to `true`, we output the code with the `Connection` type specified in [`armcore`][armcore_connection]. If not, we output a new `Connection` constructor with the generated code. Defaults to `false`.
| Flag | Description |
| -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `--module=NAME` | The name of the module. This is the name your module will be published under. |
| `--file-prefix=PREFIX` | Optional prefix to file names. For example, if you set your file prefix to "zzz", all generated code files will begin with "zzz". |
| `--openapi-type=arm\|data-plane` | Specify if you want to generate `data-plane` code or `arm` code. |
| `--armcore-connection` | If set to `true`, we output the code with the `Connection` type specified in [`armcore`][armcore_connection]. If not, we output a new `Connection` constructor with the generated code. Defaults to `false`. |
## Debugging flags
| Flag | Description | Python | .NET | Java | TS | Go
|------------------|-------------|-------------|-------------|-------------|-------------|-------------
|`--verbose`| Log verbose-level information during generation time | x | x | x | x | x
|`--debug`| Log debug-level information during generation time | x | x | x | x | x
|`--{language-generator}-debugger`| Debug into a specific language's code. See our [debugging docs][debugging] to see if there are extra steps needed to for your language generator of choice | x | x | x | x | x
|`--save-inputs`|Whether to save the configuration files (i.e. `Configuration.json` or `codeyaml.json`). Defaults to `false`.| | x| | | | |
| Flag | Description | Python | .NET | Java | TS | Go |
| --------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | ------ | ---- | ---- | --- | --- | --- |
| `--verbose` | Log verbose-level information during generation time | x | x | x | x | x |
| `--debug` | Log debug-level information during generation time | x | x | x | x | x |
| `--{language-generator}-debugger` | Debug into a specific language's code. See our [debugging docs][debugging] to see if there are extra steps needed to for your language generator of choice | x | x | x | x | x |
| `--save-inputs` | Whether to save the configuration files (i.e. `Configuration.json` or `codeyaml.json`). Defaults to `false`. | | x | | | | |
## Deprecated / Not-Recommended Flags
| Flag | Description | Python | .NET | Java | TS | Go
|------------------|-------------|-------------|-------------|-------------|-------------|-------------
|`--payload-flattening-threshold=NUMBER`|The maximum number of properties in the request body. If the number of properties in the request body is less than or equal to this value, these properties will be represented as method arguments. Not recommended because it can cause surprise breaking changes when adding properties. | x | x | x | x | x
|`--add-credentials`|Same as flag `--add-credential`, renamed because we only add one `credential` param in this case. | x | x | x | x | x
| Flag | Description | Python | .NET | Java | TS | Go |
| --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------ | ---- | ---- | --- | --- |
| `--payload-flattening-threshold=NUMBER` | The maximum number of properties in the request body. If the number of properties in the request body is less than or equal to this value, these properties will be represented as method arguments. Not recommended because it can cause surprise breaking changes when adding properties. | x | x | x | x | x |
| `--add-credentials` | Same as flag `--add-credential`, renamed because we only add one `credential` param in this case. | x | x | x | x | x |
<!-- LINKS -->
[tracing_quickstart]: https://github.com/Azure/azure-sdk-for-python/blob/master/sdk/core/azure-core-tracing-opentelemetry/README.md
[azure_sdk_for_python]: https://github.com/Azure/azure-sdk-for-python/tree/master/sdk
[mgmt_plane_section]: https://github.com/Azure/autorest/blob/master/docs/generate/readme.md#generating-management-plane-code
[mgmt_plane_section]: https://github.com/Azure/autorest/blob/main/docs/generate/readme.md#generating-management-plane-code
[setup_py]: https://packaging.python.org/tutorials/packaging-projects/#creating-setup-py
[multiapi_section]: https://github.com/Azure/autorest/blob/master/docs/generate/readme.md#generating-multi-api-code
[multiapi_section]: https://github.com/Azure/autorest/blob/main/docs/generate/readme.md#generating-multi-api-code
[namespace_folders]: https://packaging.python.org/guides/packaging-namespace-packages/#pkgutil-style-namespace-packages
[bearer_token_credential_policy]: https://docs.microsoft.com/en-us/python/api/azure-core/azure.core.pipeline.policies.bearertokencredentialpolicy?view=azure-python
[azure_key_credential_policy]: https://docs.microsoft.com/en-us/python/api/azure-core/azure.core.pipeline.policies.azurekeycredentialpolicy?view=azure-python
@ -141,8 +144,8 @@ Those flags are temporary and will be removed in the future. Those flags are her
[artifact_id]: https://maven.apache.org/guides/mini/guide-naming-conventions.html
[fluent_docs]: https://github.com/Azure/autorest.java#additional-settings-for-fluent
[armcore_connection]: https://github.com/Azure/azure-sdk-for-go/blob/master/sdk/armcore/connection.go
[debugging]: https://github.com/Azure/autorest/blob/master/docs/troubleshooting.md#debugging
[debugging]: https://github.com/Azure/autorest/blob/main/docs/troubleshooting.md#debugging
[black]: https://pypi.org/project/black/
[ts_async_iterator]: https://www.typescriptlang.org/docs/handbook/release-notes/typescript-2-3.html#async-iterators
[client]: https://github.com/Azure/autorest/blob/master/docs/client/readme.md
[adding_tags_when_generating]: https://github.com/Azure/autorest/blob/master/docs/generate/readme.md#adding-tags-when-generating
[client]: https://github.com/Azure/autorest/blob/main/docs/client/readme.md
[adding_tags_when_generating]: https://github.com/Azure/autorest/blob/main/docs/generate/readme.md#adding-tags-when-generating

18
docs/generate/readme.md
Просмотреть файл

@ -401,12 +401,12 @@ For language-specific information about generation, please refer to our language
<!-- LINKS -->
[flags]: https://github.com/Azure/autorest/blob/master/docs/generate/flags.md
[openapi_docs]: https://github.com/Azure/autorest/blob/master/docs/openapi/readme.md
[pets_swagger]: https://github.com/Azure/autorest/blob/master/docs/openapi/examples/pets.json
[basic_example]: https://github.com/Azure/autorest/blob/master/docs/generate/examples/basic/readme.md
[pets_v2_swagger]: https://github.com/Azure/autorest/blob/master/docs/openapi/examples/petsv2.json
[tags_readme]: https://github.com/Azure/autorest/blob/master/docs/generate/examples/tags/readme.md
[flags]: https://github.com/Azure/autorest/blob/main/docs/generate/flags.md
[openapi_docs]: https://github.com/Azure/autorest/blob/main/docs/openapi/readme.md
[pets_swagger]: https://github.com/Azure/autorest/blob/main/docs/openapi/examples/pets.json
[basic_example]: https://github.com/Azure/autorest/blob/main/docs/generate/examples/basic/readme.md
[pets_v2_swagger]: https://github.com/Azure/autorest/blob/main/docs/openapi/examples/petsv2.json
[tags_readme]: https://github.com/Azure/autorest/blob/main/docs/generate/examples/tags/readme.md
[azure_rest_api_specs]: https://github.com/Azure/azure-rest-api-specs
[mgmt_storage]: https://github.com/Azure/azure-rest-api-specs/tree/master/specification/storage/resource-manager
[how_autorest]: ./how-autorest-generates-code-from-openapi.md
@ -415,8 +415,8 @@ For language-specific information about generation, please refer to our language
[csharp]: https://github.com/Azure/autorest.csharp/tree/feature/v3/readme.md
[azure_sdk_for_python]: https://github.com/Azure/azure-sdk-for-python/tree/master/sdk
[azure_sdk_for_java]: https://github.com/Azure/azure-sdk-for-java/tree/master/sdk
[client]: https://github.com/Azure/autorest/blob/master/docs/client/readme.md
[openapi_introduction]: https://github.com/Azure/autorest/blob/master/docs/openapi/readme.md
[client]: https://github.com/Azure/autorest/blob/main/docs/client/readme.md
[openapi_introduction]: https://github.com/Azure/autorest/blob/main/docs/openapi/readme.md
[python_multiapi]: https://github.com/Azure/autorest.python/blob/autorestv3/docs/generate/multiapi.md
[mgmt_plane]: https://docs.microsoft.com/en-us/azure/azure-resource-manager/management/control-plane-and-data-plane#control-plane
[directives]: https://github.com/Azure/autorest/blob/master/docs/generate/directives.md
[directives]: https://github.com/Azure/autorest/blob/main/docs/generate/directives.md

4
docs/migrate/readme.md
Просмотреть файл

@ -34,8 +34,8 @@ For language-specific information about migration and changes, please refer to o
<!-- LINKS -->
[install]: https://github.com/Azure/autorest/blob/master/docs/install/readme.md
[language_flags]: https://github.com/Azure/autorest/blob/master/docs/generate/readme.md#language-flags
[install]: https://github.com/Azure/autorest/blob/main/docs/install/readme.md
[language_flags]: https://github.com/Azure/autorest/blob/main/docs/generate/readme.md#language-flags
[guidelines]: https://azure.github.io/azure-sdk/general_introduction.html
[python]: https://github.com/Azure/autorest.python/tree/autorestv3/docs/migrate/readme.md
[java]: https://github.com/Azure/autorest.java/tree/v4/docs/migrate/readme.md

18
docs/readme.md
Просмотреть файл

@ -38,13 +38,13 @@
<!-- LINKS -->
[introduction]: https://github.com/Azure/autorest/blob/master/docs/introduction.md
[install]: https://github.com/Azure/autorest/blob/master/docs/install/readme.md
[openapi]: https://github.com/Azure/autorest/blob/master/docs/openapi/readme.md
[generate]: https://github.com/Azure/autorest/blob/master/docs/generate/readme.md
[client]: https://github.com/Azure/autorest/blob/master/docs/client/readme.md
[migrate]: https://github.com/Azure/autorest/blob/master/docs/migrate/readme.md
[dev]: https://github.com/Azure/autorest/blob/master/docs/developer/readme.md
[introduction]: https://github.com/Azure/autorest/blob/main/docs/introduction.md
[install]: https://github.com/Azure/autorest/blob/main/docs/install/readme.md
[openapi]: https://github.com/Azure/autorest/blob/main/docs/openapi/readme.md
[generate]: https://github.com/Azure/autorest/blob/main/docs/generate/readme.md
[client]: https://github.com/Azure/autorest/blob/main/docs/client/readme.md
[migrate]: https://github.com/Azure/autorest/blob/main/docs/migrate/readme.md
[dev]: https://github.com/Azure/autorest/blob/main/docs/developer/readme.md
[powershell]: https://github.com/Azure/autorest.powershell/blob/master/docs/readme.md
[troubleshooting]: https://github.com/Azure/autorest/blob/master/docs/troubleshooting.md
[faq]: https://github.com/Azure/autorest/blob/master/docs/faq.md
[troubleshooting]: https://github.com/Azure/autorest/blob/main/docs/troubleshooting.md
[faq]: https://github.com/Azure/autorest/blob/main/docs/faq.md

4
docs/troubleshooting.md
Просмотреть файл

@ -37,11 +37,11 @@ If you would like to actually debug through a language generator's code, see our
<!-- LINKS -->
[main_docs]: https://github.com/Azure/autorest/blob/master/docs/openapi/readme.md
[main_docs]: https://github.com/Azure/autorest/blob/main/docs/openapi/readme.md
[autorest_issues]: https://github.com/Azure/autorest/issues
[autorest_python_issues]: https://github.com/Azure/autorest.python/issues
[autorest_python_repo]: https://github.com/Azure/autorest.python/tree/autorestv3
[debugging_flags]: https://github.com/Azure/autorest/blob/master/docs/generate/flags.md#debugging-flags
[debugging_flags]: https://github.com/Azure/autorest/blob/main/docs/generate/flags.md#debugging-flags
[python_generation]: https://github.com/Azure/autorest.python/tree/autorestv3/docs/troubleshooting.md#generation-errors
[csharp_generation]: https://github.com/Azure/autorest.csharp/tree/feature/v3/docs/troubleshooting.md#generation-errors
[typescript_generation]: https://github.com/Azure/autorest.typescript/tree/v6/docs/troubleshooting.md#generation-errors

2
markdown-link-check-config.json
Просмотреть файл

@ -2,7 +2,7 @@
"ignorePatterns": [],
"replacementPatterns": [
{
"pattern": "https://github\\.com/Azure/autorest/(?:blob|tree)/master/",
"pattern": "https://github\\.com/Azure/autorest/(?:blob|tree)/main/",
"replacement": "{{BASEURL}}/"
}
],

4
packages/apps/autorest/package.json
Просмотреть файл

@ -9,8 +9,8 @@
"type": "git",
"url": "https://github.com/Azure/autorest"
},
"homepage": "https://github.com/Azure/autorest#readme",
"readme": "https://github.com/Azure/autorest/blob/master/readme.md",
"homepage": "https://github.com/Azure/autorest",
"readme": "https://github.com/Azure/autorest/blob/main/readme.md",
"keywords": [
"autorest",
"rest",

2
packages/extensions/core/package.json
Просмотреть файл

@ -20,7 +20,7 @@
"url": "https://github.com/Azure/autorest/issues"
},
"homepage": "https://github.com/Azure/autorest#readme",
"readme": "https://github.com/Azure/autorest/blob/master/readme.md",
"readme": "https://github.com/Azure/autorest/blob/main/readme.md",
"main": "./dist/exports.js",
"bin": {
"autorest-core": "./entrypoints/app.js",

2
packages/extensions/core/src/lib/plugins/semantics-validation/validators/refs-siblings-validator.test.ts
Просмотреть файл

@ -34,7 +34,7 @@ describe("Semantic Validation: $ref siblings", () => {
level: "warn",
code: SemanticErrorCodes.IgnoredPropertyNextToRef,
message:
"Sibling values alongside $ref will be ignored. See https://github.com/Azure/autorest/blob/master/docs/openapi/howto/$ref-siblings.md for allowed values",
"Sibling values alongside $ref will be ignored. See https://github.com/Azure/autorest/blob/main/docs/openapi/howto/$ref-siblings.md for allowed values",
params: { keys: ["type"] },
path: ["components", "schemas", "Pet", "properties", "foo"],
},

2
packages/extensions/core/src/lib/plugins/semantics-validation/validators/refs-siblings-validator.ts
Просмотреть файл

@ -30,7 +30,7 @@ export function validateRefsSiblings(spec: oai3.Model) {
errors.push({
level: "warn",
code: SemanticErrorCodes.IgnoredPropertyNextToRef,
message: `Sibling values alongside $ref will be ignored. See https://github.com/Azure/autorest/blob/master/docs/openapi/howto/$ref-siblings.md for allowed values`,
message: `Sibling values alongside $ref will be ignored. See https://github.com/Azure/autorest/blob/main/docs/openapi/howto/$ref-siblings.md for allowed values`,
path,
params: {
keys,

4
packages/extensions/modelerfour/package.json
Просмотреть файл

@ -36,8 +36,8 @@
"bugs": {
"url": "https://github.com/Azure/autorest.modelerfour/issues"
},
"homepage": "https://github.com/Azure/autorest.modelerfour/tree/master/modelerfour#readme",
"readme": "https://github.com/Azure/autorest.modelerfour/tree/master/modelerfour/readme.md",
"homepage": "https://github.com/Azure/autorest/tree/main/packages/extensions/modelerfour",
"readme": "https://github.com/Azure/autorest/tree/main/packages/extensions/modelerfour/readme.md",
"devDependencies": {
"@autorest/codemodel": "~4.15.0",
"@autorest/extension-base": "~3.2.1",

2
packages/extensions/modelerfour/readme.md
Просмотреть файл

@ -17,7 +17,7 @@ contact [opencode@microsoft.com](mailto:opencode@microsoft.com) with any additio
### Autorest plugin configuration
- Please don't edit this section unless you're re-configuring how the powershell extension plugs in to AutoRest
AutoRest needs the below config to pick this up as a plug-in - see https://github.com/Azure/autorest/blob/master/docs/developer/architecture/AutoRest-extension.md
AutoRest needs the below config to pick this up as a plug-in - see https://github.com/Azure/autorest/blob/main/docs/developer/architecture/AutoRest-extension.md
### ModelFour Options

4
packages/libs/codemodel/package.json
Просмотреть файл

@ -33,8 +33,8 @@
"bugs": {
"url": "https://github.com/Azure/autorest/issues"
},
"homepage": "https://github.com/Azure/autorest/tree/master/packages/libs/codemodel#readme",
"readme": "https://github.com/Azure/autorest/tree/master/packages/libs/codemodel/readme.md",
"homepage": "https://github.com/Azure/autorest/tree/main/packages/libs/codemodel#readme",
"readme": "https://github.com/Azure/autorest/tree/main/packages/libs/codemodel/readme.md",
"devDependencies": {
"@types/js-yaml": "~4.0.0",
"@types/node": "~14.14.20",

2
packages/libs/common/package.json
Просмотреть файл

@ -26,7 +26,7 @@
"bugs": {
"url": "https://github.com/Azure/autorest/issues"
},
"homepage": "https://github.com/Azure/autorest/tree/master/packages/libs/common",
"homepage": "https://github.com/Azure/autorest/tree/main/packages/libs/common",
"devDependencies": {
"@types/jest": "^26.0.20",
"@types/node": "~14.14.20",

2
packages/libs/configuration/src/configuration-file-resolver.ts
Просмотреть файл

@ -67,7 +67,7 @@ export const detectConfigurationFiles = async (
}
// this *was* an actual file passed in, not a folder. don't make this harder than it has to be.
throw new Error(
`Specified file '${originalConfigFileOrFolderUri}' is not a valid configuration file (missing magic string, see https://github.com/Azure/autorest/blob/master/docs/user/literate-file-formats/configuration.md#the-file-format).`,
`Specified file '${originalConfigFileOrFolderUri}' is not a valid configuration file (missing magic string, see https://github.com/Azure/autorest/blob/main/docs/user/literate-file-formats/configuration.md#the-file-format).`,
);
}

4
packages/libs/datastore/package.json
Просмотреть файл

@ -33,8 +33,8 @@
"bugs": {
"url": "https://github.com/Azure/perks/issues"
},
"homepage": "https://github.com/Azure/perks/tree/master/datastore#readme",
"readme": "https://github.com/Azure/perks/tree/master/datastore/readme.md",
"homepage": "https://github.com/Azure/autorest/tree/main/packages/libs/datastore",
"readme": "https://github.com/Azure/autorest/tree/main/packages/libs/datastore/readme.md",
"devDependencies": {
"@types/jest": "^26.0.20",
"@types/jsonpath": "^0.2.0",

8
packages/libs/datastore/src/file-system/real-file-system.test.ts
Просмотреть файл

@ -26,18 +26,18 @@ describe("MemoryFileSystem", () => {
describe("accessing remote files", () => {
it("should looks for readme.md when listing files", async () => {
const files = await fs.list("https://github.com/Azure/autorest/blob/master/");
const files = await fs.list("https://github.com/Azure/autorest/blob/main/");
expect(files).toHaveLength(1);
expect(files[0]).toEqual("https://github.com/Azure/autorest/blob/master/readme.md");
expect(files[0]).toEqual("https://github.com/Azure/autorest/blob/main/readme.md");
});
it("should read local file content", async () => {
expect(await fs.read("https://github.com/Azure/autorest/blob/master/readme.md")).toContain("Autorest");
expect(await fs.read("https://github.com/Azure/autorest/blob/main/readme.md")).toContain("Autorest");
});
it("should throw error if the local file doesn't exists", async () => {
await expect(() =>
fs.read("https://github.com/Azure/autorest/blob/master/this-file-doesnot-exists.md"),
fs.read("https://github.com/Azure/autorest/blob/main/this-file-doesnot-exists.md"),
).rejects.toThrowError(UriNotFoundError);
});
});

4
packages/libs/deduplication/package.json
Просмотреть файл

@ -33,8 +33,8 @@
"bugs": {
"url": "https://github.com/Azure/perks/issues"
},
"homepage": "https://github.com/Azure/perks/tree/master/deduplication#readme",
"readme": "https://github.com/Azure/perks/tree/master/deduplication/readme.md",
"homepage": "https://github.com/Azure/autorest/tree/main/packages/libs/deduplication",
"readme": "https://github.com/Azure/autorest/tree/main/packages/libs/deduplication/readme.md",
"devDependencies": {
"@types/jest": "^26.0.20",
"@types/node": "~14.14.20",

4
packages/libs/extension/package.json
Просмотреть файл

@ -33,8 +33,8 @@
"bugs": {
"url": "https://github.com/Azure/perks/issues"
},
"homepage": "https://github.com/Azure/perks/tree/master/extension#readme",
"readme": "https://github.com/Azure/perks/tree/master/extension/readme.md",
"homepage": "https://github.com/Azure/autorest/tree/main/packages/libs/extension",
"readme": "https://github.com/Azure/autorest/tree/main/packages/libs/extension/readme.md",
"old": {
"@types/npm": "^2.0.28",
"npm": "5.6.0"

2
packages/libs/json/package.json
Просмотреть файл

@ -26,7 +26,7 @@
"bugs": {
"url": "https://github.com/Azure/autorest/issues"
},
"homepage": "https://github.com/Azure/autorest/tree/master/packages/libs/json",
"homepage": "https://github.com/Azure/autorest/tree/main/packages/libs/json",
"devDependencies": {
"@types/jest": "^26.0.20",
"@types/node": "~14.14.20",

2
packages/libs/jsonschema/package.json
Просмотреть файл

@ -26,7 +26,7 @@
"bugs": {
"url": "https://github.com/Azure/autorest/issues"
},
"homepage": "https://github.com/Azure/autorest/tree/master/packages/libs/jsonschema",
"homepage": "https://github.com/Azure/autorest/tree/main/packages/libs/jsonschema",
"devDependencies": {
"@types/jest": "^26.0.20",
"@types/node": "~14.14.20",

4
packages/libs/oai2-to-oai3/package.json
Просмотреть файл

@ -33,8 +33,8 @@
"bugs": {
"url": "https://github.com/Azure/perks/issues"
},
"homepage": "https://github.com/Azure/perks/tree/master/oai2-to-oai3#readme",
"readme": "https://github.com/Azure/perks/tree/master/oai2-to-oai3/readme.md",
"homepage": "https://github.com/Azure/autorest/tree/main/packages/libs/oai2-to-oai3",
"readme": "https://github.com/Azure/autorest/tree/main/packages/libs/oai2-to-oai3/readme.md",
"devDependencies": {
"@autorest/test-utils": "~0.2.2",
"@types/jest": "^26.0.20",

4
packages/libs/openapi/package.json
Просмотреть файл

@ -33,8 +33,8 @@
"bugs": {
"url": "https://github.com/Azure/perks/issues"
},
"homepage": "https://github.com/Azure/perks/tree/master/openapi#readme",
"readme": "https://github.com/Azure/perks/tree/master/openapi/readme.md",
"homepage": "https://github.com/Azure/autorest/tree/main/packages/libs/openapi",
"readme": "https://github.com/Azure/autorest/tree/main/packages/libs/openapi/readme.md",
"devDependencies": {
"@types/jest": "^26.0.20",
"@types/node": "~14.14.20",

5
rush.json
Просмотреть файл

@ -9,7 +9,10 @@
"ensureConsistentVersions": true,
"projectFolderMinDepth": 3,
"projectFolderMaxDepth": 3,
"repository": {},
"repository": {
"defaultBranch": "main",
"url": "https://github.com/Azure/autorest"
},
"eventHooks": {
"preRushInstall": [],
"postRushInstall": [],