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

fix autorest links

This commit is contained in:
iscai-msft 2021-01-11 16:03:27 -05:00
Родитель 8c68bc4689
Коммит c5a60d0d92
11 изменённых файлов: 72 добавлений и 74 удалений
Показать статистику Скачать Patch файл Скачать Diff файл Показать все файлы Свернуть все файлы

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

@ -7,7 +7,7 @@ This is highly-language specific, so please refer to the documentation we have f
- [Typescript][typescript] - [Typescript][typescript]
<!--LINKS--> <!--LINKS-->
[python]: https://github.com/Azure/autorest.python/tree/autorestv3/docs/client [python]: https://github.com/Azure/autorest.python/tree/autorestv3/docs/client/readme.md
[java]: https://github.com/Azure/autorest.java/tree/v4/docs/client [java]: https://github.com/Azure/autorest.java/tree/v4/docs/client/readme.md
[csharp]: https://github.com/Azure/autorest.csharp/tree/v3/docs/client [csharp]: https://github.com/Azure/autorest.csharp/tree/v3/docs/client/readme.md
[typescript]: https://github.com/Azure/autorest.typescript/tree/v6/docs/client [typescript]: https://github.com/Azure/autorest.typescript/tree/v6/docs/client/readme.md

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

@ -3,4 +3,4 @@
Current docs are [here][writing_an_extension], more incoming Current docs are [here][writing_an_extension], more incoming
<!-- LINKS --> <!-- LINKS -->
[writing_an_extension]: writing-an-extension.md [writing_an_extension]: https://github.com/Azure/autorest/blob/master/docs/developer/writing-an-extension.md

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

@ -904,9 +904,6 @@ Task<IPage<int?>> ListAsync(ISimpleAPIClient operations, CancellationToken cance
IPage<int?> ListNext(ISimpleAPIClient operations, string nextPageLink); IPage<int?> ListNext(ISimpleAPIClient operations, string nextPageLink);
Task<IPage<int?>> ListNextAsync(ISimpleAPIClient operations, string nextPageLink, CancellationToken cancellationToken); Task<IPage<int?>> ListNextAsync(ISimpleAPIClient operations, string nextPageLink, CancellationToken cancellationToken);
``` ```
Full code:
[example1.yaml](x-ms-pageable/example1.yaml),
[example1.cs](x-ms-pageable/example1.cs)
**Example 2: Customized** **Example 2: Customized**
@ -951,9 +948,6 @@ Task<IPage<int?>> ListAsync(ISimpleAPIClient operations, CancellationToken cance
IPage<int?> ListMore(ISimpleAPIClient operations, string nextPageLink); IPage<int?> ListMore(ISimpleAPIClient operations, string nextPageLink);
Task<IPage<int?>> ListMoreAsync(ISimpleAPIClient operations, string nextPageLink, CancellationToken cancellationToken); Task<IPage<int?>> ListMoreAsync(ISimpleAPIClient operations, string nextPageLink, CancellationToken cancellationToken);
``` ```
Full code:
[example2.yaml](x-ms-pageable/example2.yaml),
[example2.cs](x-ms-pageable/example2.cs)
**Example 3: Single page result** **Example 3: Single page result**
@ -993,10 +987,6 @@ Generated signatures:
IEnumerable<int?> List(ISimpleAPIClient operations); IEnumerable<int?> List(ISimpleAPIClient operations);
Task<IEnumerable<int?>> ListAsync(ISimpleAPIClient operations, CancellationToken cancellationToken); Task<IEnumerable<int?>> ListAsync(ISimpleAPIClient operations, CancellationToken cancellationToken);
``` ```
Full code:
[example3.yaml](x-ms-pageable/example3.yaml),
[example3.cs](x-ms-pageable/example3.cs)
## x-ms-long-running-operation ## 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. 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.

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

@ -95,7 +95,8 @@ We'll go over both in this example. In both cases, we'll be looking to rename pa
``` ```
Referring to the parameter's location in the operation, our filter would be `where: '$.paths["/vm"].get.parameters[0]'`. We're changing the name of the parameter, Referring to the parameter's location in the operation, our filter would be `where: '$.paths["/vm"].get.parameters[0]'`. We're changing the name of the parameter,
so our transform would apply to the `name` field (or the [`x-ms-client-name`] field if we've defined one for the parameter). This becomes so you could apply your transform to the `name` field. However, it's better to change the [`x-ms-client-name`][x_ms_client_name] field instead, since there could be
this field defined for your parameter, and this field overrides the `name` field. This becomes
``` yaml ``` yaml
### Directive renaming "getVirtualMachine"'s parameter "id" to "identifier". ### Directive renaming "getVirtualMachine"'s parameter "id" to "identifier".
@ -103,7 +104,7 @@ directive:
from: swagger-document from: swagger-document
where: '$.paths["/vm"].get.parameters[0]' where: '$.paths["/vm"].get.parameters[0]'
transform: > transform: >
$["name"] = "identifier"; $["x-ms-client-name"] = "identifier";
``` ```
#### Parameter defined in the "Parameters" section #### Parameter defined in the "Parameters" section
@ -128,7 +129,7 @@ directive:
from: swagger-document from: swagger-document
where: '$.parameters["Id"]' where: '$.parameters["Id"]'
transform: > transform: >
$["name"] = "identifier"; $["x-ms-client-name"] = "identifier";
``` ```
### Model Rename ### Model Rename
@ -232,7 +233,7 @@ directive:
from: swagger-document from: swagger-document
where: '$.definitions.VM.properties.virtualMachineType.x-ms-enum.values[0]' where: '$.definitions.VM.properties.virtualMachineType.x-ms-enum.values[0]'
transform: > transform: >
$["name"] = "AzureVirtualMachine"; $["x-ms-client-name"] = "AzureVirtualMachine";
``` ```
Now, we would access the enum through `VirtualMachineTypes.AzureVirtualMachine` instead of `VirtualMachineTypes.AzureVM`. Now, we would access the enum through `VirtualMachineTypes.AzureVirtualMachine` instead of `VirtualMachineTypes.AzureVM`.
@ -241,7 +242,7 @@ Now, we would access the enum through `VirtualMachineTypes.AzureVirtualMachine`
Changing a description is very similar whether you're changing an operation's description or a model's description etc. The only thing that varies is how to refer to the object whose description your changing. Since this is covered in the previous examples, we won't do separate sections for this. Instead, we will show you how to change a property's description, which can be easily extended to another object, i.e. an operation. Changing a description is very similar whether you're changing an operation's description or a model's description etc. The only thing that varies is how to refer to the object whose description your changing. Since this is covered in the previous examples, we won't do separate sections for this. Instead, we will show you how to change a property's description, which can be easily extended to another object, i.e. an operation.
Let's say we [renamed the property](#property-rename "renamed the property") from `id` to `identifier`, and we want to change all references in the description of `id` to `identifier`: Let's say we [renamed the property](#property-rename "Property Rename") from `id` to `identifier`, and we want to change all references in the description of `id` to `identifier`:
```yaml ```yaml
... ...

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

@ -7,10 +7,11 @@
|`--output-folder=DIRECTORY`|The location for generated files. If not specified, uses `./generated` as the default| 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 |`--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 |`--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 [TODO] 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. |`--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` |`--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 |`--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 | | |`--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 |`--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`. |`--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 |`--title=NAME`|Override the service client's name listed in the swagger under `title`.| x | x | x | x | x
@ -38,7 +39,7 @@
| Flag | Description | Flag | Description
|------------------|------------- |------------------|-------------
|`--library-name=NAME`|The name of your library. This is what will be displayed on NuGet. |`--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 |`--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`. |`--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`. |`--model-namespace`|Whether to add a separate namespace of Models, more specifically adding `{value-from-namespace-flag}.Models`. Defaults to `true`.
@ -55,7 +56,7 @@
|`--implementation-subpackage=NAME`|The sub-package that the Service client and Method Group client implementation classes will be put into. Defaults to `implementation`. |`--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`. |`--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`. |`--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` parameter should also be included in generated client methods. Forces `--add-context-parameter` to `true`. 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 |`--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`. |`--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-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`.
@ -109,12 +110,12 @@
<!-- LINKS --> <!-- LINKS -->
[tracing_quickstart]: https://github.com/Azure/azure-sdk-for-python/blob/master/sdk/core/azure-core-tracing-opentelemetry/README.md [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 [azure_sdk_for_python]: https://github.com/Azure/azure-sdk-for-python/tree/master/sdk
[mgmt_plane_section]: ./readme.md#generating-management-plane-code [mgmt_plane_section]: https://github.com/Azure/autorest/blob/master/docs/generate/readme.md#generating-management-plane-code
[setup_py]: https://packaging.python.org/tutorials/packaging-projects/#creating-setup-py [setup_py]: https://packaging.python.org/tutorials/packaging-projects/#creating-setup-py
[multiapi_section]: ./readme.md#generating-multiapi-code [multiapi_section]: https://github.com/Azure/autorest/blob/master/docs/generate/readme.md#generating-multi-api-code
[namespace_folders]: https://packaging.python.org/guides/packaging-namespace-packages/#pkgutil-style-namespace-packages [namespace_folders]: https://packaging.python.org/guides/packaging-namespace-packages/#pkgutil-style-namespace-packages
[bearer_token_credential_policy]: https://azuresdkdocs.blob.core.windows.net/$web/python/azure-core/latest/azure.core.pipeline.policies.html#azure.core.pipeline.policies.BearerTokenCredentialPolicy [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://azuresdkdocs.blob.core.windows.net/$web/python/azure-core/latest/azure.core.pipeline.policies.html#azure.core.pipeline.policies.AzureKeyCredentialPolicy [azure_key_credential_policy]: https://docs.microsoft.com/en-us/python/api/azure-core/azure.core.pipeline.policies.azurekeycredentialpolicy?view=azure-python
[shared_generator_assets]: https://github.com/Azure/autorest.csharp/tree/feature/v3/src/assets/Generator.Shared [shared_generator_assets]: https://github.com/Azure/autorest.csharp/tree/feature/v3/src/assets/Generator.Shared
[shared_azure_core_assets]: https://github.com/Azure/autorest.csharp/tree/feature/v3/src/assets/Azure.Core.Shared [shared_azure_core_assets]: https://github.com/Azure/autorest.csharp/tree/feature/v3/src/assets/Azure.Core.Shared
[autorest_csharp]: https://github.com/Azure/autorest.csharp [autorest_csharp]: https://github.com/Azure/autorest.csharp
@ -124,6 +125,8 @@
[artifact_id]: https://maven.apache.org/guides/mini/guide-naming-conventions.html [artifact_id]: https://maven.apache.org/guides/mini/guide-naming-conventions.html
[fluent_docs]: https://github.com/Azure/autorest.java#additional-settings-for-fluent [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 [armcore_connection]: https://github.com/Azure/azure-sdk-for-go/blob/master/sdk/armcore/connection.go
[debugging]: ../troubleshooting.md#debugging [debugging]: https://github.com/Azure/autorest/blob/master/docs/troubleshooting.md#debugging
[black]: https://pypi.org/project/black/ [black]: https://pypi.org/project/black/
[ts_async_iterator]: https://www.typescriptlang.org/docs/handbook/release-notes/typescript-2-3.html#async-iterators [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

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

@ -34,7 +34,7 @@ For a full-set of flags, go to our [flag index][flags]
|`--output-folder=DIRECTORY`|The location for generated files. If not specified, uses `./generated` as the default| |`--output-folder=DIRECTORY`|The location for generated files. If not specified, uses `./generated` as the default|
|`--clear-output-folder`|Clear all contents from our output folder before outputting your newly generated code into that folder| |`--clear-output-folder`|Clear all contents from our output folder before outputting your newly generated code into that folder|
|`--namespace=NAMESPACE`|sets the namespace to use for the generated code| |`--namespace=NAMESPACE`|sets the namespace to use for the generated code|
|`--add-credential`|If specified, the generated client will require a credential to make network calls. See [TODO] for information on how to authenticate to our generated clients| |`--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.|
|`--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 "Adding Tags When Generating") section for more information| |`--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 "Adding Tags When Generating") section for more information|
## Most Basic: Generating with a Single File on the Command Line ## Most Basic: Generating with a Single File on the Command Line
@ -217,7 +217,7 @@ A common occurrence is wanting to generate your SDK in multiple languages. Since
for each language. In this example, we will show how to generate in both Java and Python. In situations like this, it is preferred to have one main for each language. In this example, we will show how to generate in both Java and Python. In situations like this, it is preferred to have one main
language agnostic configuration file titled `readme.md`, where you list the configuration you want regardless of language. Then, you create a configuration file for every language you want with the language name in the path. In this case, we would create a `readme.java.md`, and a `readme.python.md`. These configuration files will be linked to from the main `readme.md`. language agnostic configuration file titled `readme.md`, where you list the configuration you want regardless of language. Then, you create a configuration file for every language you want with the language name in the path. In this case, we would create a `readme.java.md`, and a `readme.python.md`. These configuration files will be linked to from the main `readme.md`.
Let's start with the configurations we want in the main `readme.md`. Following from the [previous example](#adding-tags-when-generating), we want to generate [pets.json](../../openapi/examples/pets.json) if `--tag=v1` is specified on the command line, and [petsv2.json](../../openapi/examples/petsv2.json) if `--tag=v2` is specified, regardless of which language we're generating in. We also need to link to our `readme.python.md` and `readme.java.md` from this main readme. Let's start with the configurations we want in the main `readme.md`. Following from the [previous example](#adding-tags-when-generating), we want to generate [pets.json][pets_swagger] if `--tag=v1` is specified on the command line, and [petsv2.json][pets_v2_swagger] if `--tag=v2` is specified, regardless of which language we're generating in. We also need to link to our `readme.python.md` and `readme.java.md` from this main readme.
This gives us the following `readme.md`: This gives us the following `readme.md`:
@ -337,7 +337,7 @@ If we want to generate `v1` code in either language, all that's needed is to tac
## Generating Management Plane Code ## Generating Management Plane Code
There are a couple of steps that are more [management-plane](https://docs.microsoft.com/en-us/azure/azure-resource-manager/management/control-plane-and-data-plane#control-plane) specific, which this section will go into. There are a couple of steps that are more [management-plane][mgmt_plane] specific, which this section will go into.
The biggest thing to keep in mind when generating management plane code is using the flag `--azure-arm`. This tells the language generators you want management plane code. Since management plane code is more standardized, we are able to generate more specialized code. Setting this `azure-arm` flag also has implications for other flags (i.e., it forces `head-as-boolean` to be true). See our [flag index][flags] for more information. The biggest thing to keep in mind when generating management plane code is using the flag `--azure-arm`. This tells the language generators you want management plane code. Since management plane code is more standardized, we are able to generate more specialized code. Setting this `azure-arm` flag also has implications for other flags (i.e., it forces `head-as-boolean` to be true). See our [flag index][flags] for more information.
@ -345,15 +345,15 @@ The OpenAPI definitions for management plane code also live in the `resource-man
## Generating with Directives ## Generating with Directives
Directives are used to change the code generated from your OpenAPI definition. For example, if you want to change the name of a parameter in an operation without changing the swagger. See [our directives section](./directives.md) if this is something you're interested in. Directives are used to change the code generated from your OpenAPI definition. For example, if you want to change the name of a parameter in an operation without changing the swagger. See [our directives section][directives] if this is something you're interested in.
## Generating Multi API Code ## Generating Multi API Code
Only Python supports generating multiapi code, see [the Python docs](https://github.com/Azure/autorest.python/blob/autorestv3/docs/generate/readme.md) for how to generate. Only Python supports generating multiapi code, see [the Python docs][python_multiapi] for how to generate.
## Index of Flags ## Index of Flags
See [here](.flags.md) for a complete index of flags. See [here][flags] for a complete index of flags.
## Generate from Private GitHub Repos ## Generate from Private GitHub Repos
@ -382,17 +382,22 @@ For language-specific information about generation, please refer to our language
- [C#][csharp] - [C#][csharp]
<!-- LINKS --> <!-- LINKS -->
[flags]: ./flags.md [flags]: https://github.com/Azure/autorest/blob/master/docs/generate/flags.md
[openapi_docs]: ../openapi/readme.md [openapi_docs]: https://github.com/Azure/autorest/blob/master/docs/openapi/readme.md
[pets_swagger]: ../openapi/examples/pets.json [pets_swagger]: https://github.com/Azure/autorest/blob/master/docs/openapi/examples/pets.json
[basic_example]: ./examples/basic/readme.md [basic_example]: https://github.com/Azure/autorest/blob/master/docs/generate/examples/basic/readme.md
[pets_v2_swagger]: ./openapi/examples/pets.json [pets_v2_swagger]: https://github.com/Azure/autorest/blob/master/docs/openapi/examples/petsv2.json
[tags_readme]: ./examples/tags/readme.md [tags_readme]: https://github.com/Azure/autorest/blob/master/docs/generate/examples/tags/readme.md
[azure_rest_api_specs]: https://github.com/Azure/azure-rest-api-specs [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 [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 [how_autorest]: ./how-autorest-generates-code-from-openapi.md
[python]: https://github.com/Azure/autorest.python/tree/autorestv3/docs/generate [python]: https://github.com/Azure/autorest.python/tree/autorestv3/docs/generate/readme.md
[java]: https://github.com/Azure/autorest.java/tree/v4/docs/generate [java]: https://github.com/Azure/autorest.java/tree/v4/docs/generate/readme.md
[csharp]: https://github.com/Azure/autorest.csharp/tree/v3/docs/generate [csharp]: https://github.com/Azure/autorest.csharp/tree/v3/docs/generate/readme.md
[azure_sdk_for_python]: https://github.com/Azure/azure-sdk-for-python/tree/master/sdk [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 [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
[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

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

@ -1,4 +1,4 @@
# <img align="center" src="./images/logo.png"> Installing AutoRest # <img align="center" src="../images/logo.png"> Installing AutoRest
Installing AutoRest on Windows, MacOS or Linux involves two steps: Installing AutoRest on Windows, MacOS or Linux involves two steps:
@ -17,7 +17,7 @@ Installing AutoRest on Windows, MacOS or Linux involves two steps:
``` ```
3. To confirm you are using AutoRest V3, and not an older version, run `autorest --help`, and confirm your core version is 3.0 and higher. 3. To confirm you are using AutoRest V3, and not an older version, run `autorest --help`, and confirm your core version is 3.0 and higher.
We strongly recommend version `3.06318` or higher due to bug fixes. For more versioning information, see (./autorest-versioning.md) We strongly recommend version `3.06318` or higher due to bug fixes. For more versioning information, see [here][autorest_versioning].
# <img align="center" src="images/autorestCoreVersion.png"> # <img align="center" src="images/autorestCoreVersion.png">
4. If you're running into issues running AutoRest, check out our [troubleshooting][troubleshooting] docs 4. If you're running into issues running AutoRest, check out our [troubleshooting][troubleshooting] docs
@ -50,4 +50,5 @@ If you must fall back to AutoRest V2, run
``` ```
<!-- LINKS --> <!-- LINKS -->
[troubleshooting]: ../troubleshooting.md#module-errors [troubleshooting]: ../troubleshooting.md#module-errors
[autorest_versioning]: ./autorest-versioning.md

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

@ -13,7 +13,7 @@ The main [swagger docs][swagger_basic_structure] have a good example for the bas
## What is AutoRest? ## What is AutoRest?
AutoRest is a tool that provides a code generation framework for converting OpenAPI 2.0 and 3.0 specifications into client libraries for the services described by those specifications. It was developed by Microsoft around the time the OpenAPI Initiative was formed so that Azure service teams could start producing generated client libraries from new Swagger and OpenAPI 2.0 specifications. There are a few extensions that AutoRest is a tool that provides a code generation framework for converting OpenAPI 2.0 and 3.0 specifications into client libraries for the services described by those specifications. It was developed by Microsoft around the time the OpenAPI Initiative was formed so that Azure service teams could start producing generated client libraries from new Swagger and OpenAPI 2.0 specifications. AutoRest has created a [few extensions][extensions] to augment swagger functionality (a lot were created due to OpenAPI2 shortcomings).
At the core of AutoRest is a flexible pipeline where a series of pre-configured phases transform and merge various OpenAPI input files to produce a “code model” that can be consumed by a language-specific code generator. These code generator extensions will interpret the code model and produce code that aligns with the design guidelines for each language. The generated code for a language will use the corresponding Azure Core implementation so that we can provide configurable behavior for how HTTP requests are made in the generated code. At the core of AutoRest is a flexible pipeline where a series of pre-configured phases transform and merge various OpenAPI input files to produce a “code model” that can be consumed by a language-specific code generator. These code generator extensions will interpret the code model and produce code that aligns with the design guidelines for each language. The generated code for a language will use the corresponding Azure Core implementation so that we can provide configurable behavior for how HTTP requests are made in the generated code.
@ -26,4 +26,5 @@ See our [landing page][landing_page] to get started with writing your OpenAPI de
[swagger_basic_structure]: https://swagger.io/docs/specification/basic-structure/ [swagger_basic_structure]: https://swagger.io/docs/specification/basic-structure/
[swagger_docs]: https://swagger.io/docs/ [swagger_docs]: https://swagger.io/docs/
[openapi_docs]: ./openapi/readme.md [openapi_docs]: ./openapi/readme.md
[landing_page]: readme.md [landing_page]: readme.md
[extensions]: extensions/readme.md

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

@ -1,4 +1,4 @@
# <img align="center" src="./images/logo.png"> Migrating from AutoRest V2 to V3 # <img align="center" src="../images/logo.png"> Migrating from AutoRest V2 to V3
## General Guidance ## General Guidance
First, make sure when generating you are using AutoRest V3. Follow the steps in [our installation section][install] for information on upgrading First, make sure when generating you are using AutoRest V3. Follow the steps in [our installation section][install] for information on upgrading
@ -34,10 +34,10 @@ For language-specific information about migration and changes, please refer to o
<!-- LINKS --> <!-- LINKS -->
[install]: ../install/readme.md [install]: https://github.com/Azure/autorest/blob/master/docs/install/readme.md
[language_flags]: generate/readme.md#language-flags [language_flags]: https://github.com/Azure/autorest/blob/master/docs/generate/readme.md#language-flags
[guidelines]: https://azure.github.io/azure-sdk/general_introduction.html [guidelines]: https://azure.github.io/azure-sdk/general_introduction.html
[python]: https://github.com/Azure/autorest.python/tree/autorestv3/docs/migrate [python]: https://github.com/Azure/autorest.python/tree/autorestv3/docs/migrate/readme.md
[java]: https://github.com/Azure/autorest.java/tree/v4/docs/migrate [java]: https://github.com/Azure/autorest.java/tree/v4/docs/migrate/readme.md
[csharp]: https://github.com/Azure/autorest.csharp/tree/v3/docs/migrate [csharp]: https://github.com/Azure/autorest.csharp/tree/v3/docs/migrate/readme.md
[typescript]: https://github.com/Azure/autorest.typescript/tree/v6/docs/migrate [typescript]: https://github.com/Azure/autorest.typescript/tree/v6/docs/migrate/readme.md

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

@ -24,18 +24,15 @@
8. `Powershell` documentation 8. `Powershell` documentation
- [How][powershell] do I use AutoRest to build `Powershell` cmdlets? - [How][powershell] do I use AutoRest to build `Powershell` cmdlets?
9. [FAQ][faq] 9. [Troubleshooting][troubleshooting]
10. [Troubleshooting][troubleshooting]
<!-- LINKS --> <!-- LINKS -->
[introduction]: ./introduction.md [introduction]: https://github.com/Azure/autorest/blob/master/docs/introduction.md
[install]: ./install/readme.md [install]: https://github.com/Azure/autorest/blob/master/docs/install/readme.md
[openapi]: ./openapi/readme.md [openapi]: https://github.com/Azure/autorest/blob/master/docs/openapi/readme.md
[generate]: ./generate/readme.md [generate]: https://github.com/Azure/autorest/blob/master/docs/generate/readme.md
[client]: ./client/readme.md [client]: https://github.com/Azure/autorest/blob/master/docs/client/readme.md
[migrate]: ./migrate/readme.md [migrate]: https://github.com/Azure/autorest/blob/master/docs/migrate/readme.md
[dev]: ./developer/readme.md [dev]: https://github.com/Azure/autorest/blob/master/docs/developer/readme.md
[powershell]: ./powershell/readme.md [powershell]: https://github.com/Azure/autorest/blob/master/docs/powershell/readme.md
[faq]: ./faq.md [troubleshooting]: https://github.com/Azure/autorest/blob/master/docs/troubleshooting.md
[troubleshooting]: ./troubleshooting.md

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

@ -6,7 +6,7 @@ When running into an AutoRest issues actually running the AutoRest program, your
## Generation Errors ## Generation Errors
There are two broad kinds of errors you can run into when generating: one kind is thrown earlier in the AutoRest pipeline and has to do with malformed swaggers (see [our main docs][main_docs] for more information). The other kind is thrown by the language generators. There are two broad kinds of errors you can run into when generating: one kind is thrown earlier in the AutoRest pipeline and has to do with malformed swaggers (see [our OpenAPI docs][main_docs] for more information). The other kind is thrown by the language generators.
The general AutoRest errors are thrown like this, and are commonly due to swagger issues. The general AutoRest errors are thrown like this, and are commonly due to swagger issues.
@ -23,7 +23,7 @@ If you're error does not look like this, refer to the docs in our language gener
- [Typescript][typescript_generation] - [Typescript][typescript_generation]
Both of these issues should give you enough information to fix the error. If not, please let us know in either the [main repo][autorest_issues], or in the [Python repo][autorest_python_issues]. Also let us know if you believe These issues should give you enough information to fix the error. If not, please let us know in either the [main repo][autorest_issues], or in the language-specific repos. Also let us know if you believe
there are erroneous errors being thrown. there are erroneous errors being thrown.
## Debugging ## Debugging
@ -38,12 +38,12 @@ If you would like to actually debug through a language generator's code, see our
- [Typescript][typescript_debug] - [Typescript][typescript_debug]
<!-- LINKS --> <!-- LINKS -->
[main_docs]: https://github.com/Azure/autorest/tree/master/docs/generate/troubleshooting.md [main_docs]: https://github.com/Azure/autorest/blob/master/docs/openapi/readme.md
[autorest_issues]: https://github.com/Azure/autorest/issues [autorest_issues]: https://github.com/Azure/autorest/issues
[autorest_python_issues]: https://github.com/Azure/autorest.python/issues [autorest_python_issues]: https://github.com/Azure/autorest.python/issues
[main_debugging]: https://github.com/Azure/autorest/tree/master/docs/generate/troubleshooting.md#debugging [main_debugging]: https://github.com/Azure/autorest/tree/master/docs/generate/troubleshooting.md#debugging
[autorest_python_repo]: https://github.com/Azure/autorest.python/tree/autorestv3 [autorest_python_repo]: https://github.com/Azure/autorest.python/tree/autorestv3
[debugging_flags]: generate/flags.md#debugging-flags [debugging_flags]: https://github.com/Azure/autorest/blob/master/docs/generate/flags.md#debugging-flags
[python_generation]: https://github.com/Azure/autorest.python/tree/autorestv3/docs/troubleshooting.md#generation-errors [python_generation]: https://github.com/Azure/autorest.python/tree/autorestv3/docs/troubleshooting.md#generation-errors
[java_generation]: https://github.com/Azure/autorest.java/tree/v4/docs/troubleshooting.md#generation-errors [java_generation]: https://github.com/Azure/autorest.java/tree/v4/docs/troubleshooting.md#generation-errors
[csharp_generation]: https://github.com/Azure/autorest.csharp/tree/v3/docs/troubleshooting.md#generation-errors [csharp_generation]: https://github.com/Azure/autorest.csharp/tree/v3/docs/troubleshooting.md#generation-errors