diff --git a/docs/client/readme.md b/docs/client/readme.md index 1740f66a8..dab57f947 100644 --- a/docs/client/readme.md +++ b/docs/client/readme.md @@ -7,7 +7,7 @@ This is highly-language specific, so please refer to the documentation we have f - [Typescript][typescript] -[python]: https://github.com/Azure/autorest.python/tree/autorestv3/docs/client -[java]: https://github.com/Azure/autorest.java/tree/v4/docs/client -[csharp]: https://github.com/Azure/autorest.csharp/tree/v3/docs/client -[typescript]: https://github.com/Azure/autorest.typescript/tree/v6/docs/client \ No newline at end of file +[python]: https://github.com/Azure/autorest.python/tree/autorestv3/docs/client/readme.md +[java]: https://github.com/Azure/autorest.java/tree/v4/docs/client/readme.md +[csharp]: https://github.com/Azure/autorest.csharp/tree/v3/docs/client/readme.md +[typescript]: https://github.com/Azure/autorest.typescript/tree/v6/docs/client/readme.md \ No newline at end of file diff --git a/docs/developer/readme.md b/docs/developer/readme.md index 24bbc8d8a..6804920b6 100644 --- a/docs/developer/readme.md +++ b/docs/developer/readme.md @@ -3,4 +3,4 @@ Current docs are [here][writing_an_extension], more incoming -[writing_an_extension]: writing-an-extension.md +[writing_an_extension]: https://github.com/Azure/autorest/blob/master/docs/developer/writing-an-extension.md diff --git a/docs/extensions/readme.md b/docs/extensions/readme.md index e66983351..8ab023b13 100644 --- a/docs/extensions/readme.md +++ b/docs/extensions/readme.md @@ -904,9 +904,6 @@ Task> ListAsync(ISimpleAPIClient operations, CancellationToken cance IPage ListNext(ISimpleAPIClient operations, string nextPageLink); Task> 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** @@ -951,9 +948,6 @@ Task> ListAsync(ISimpleAPIClient operations, CancellationToken cance IPage ListMore(ISimpleAPIClient operations, string nextPageLink); Task> 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** @@ -993,10 +987,6 @@ Generated signatures: IEnumerable List(ISimpleAPIClient operations); Task> 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 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. diff --git a/docs/generate/directives.md b/docs/generate/directives.md index 6e2d68d23..9b88ea0b9 100644 --- a/docs/generate/directives.md +++ b/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, -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 ### Directive renaming "getVirtualMachine"'s parameter "id" to "identifier". @@ -103,7 +104,7 @@ directive: from: swagger-document where: '$.paths["/vm"].get.parameters[0]' transform: > - $["name"] = "identifier"; + $["x-ms-client-name"] = "identifier"; ``` #### Parameter defined in the "Parameters" section @@ -128,7 +129,7 @@ directive: from: swagger-document where: '$.parameters["Id"]' transform: > - $["name"] = "identifier"; + $["x-ms-client-name"] = "identifier"; ``` ### Model Rename @@ -232,7 +233,7 @@ directive: from: swagger-document where: '$.definitions.VM.properties.virtualMachineType.x-ms-enum.values[0]' transform: > - $["name"] = "AzureVirtualMachine"; + $["x-ms-client-name"] = "AzureVirtualMachine"; ``` 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. -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 ... diff --git a/docs/generate/flags.md b/docs/generate/flags.md index e2dca42c1..95bb0be4c 100644 --- a/docs/generate/flags.md +++ b/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 |`--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 [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` |`--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 @@ -38,7 +39,7 @@ | 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 +|`--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`. @@ -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`. |`--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` 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
  `essential` - generates only one sync returning body or header (default)
  `all` - generates one sync method for each async method
  `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`. @@ -109,12 +110,12 @@ [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]: ./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 -[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 -[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 -[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 +[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 [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 [autorest_csharp]: https://github.com/Azure/autorest.csharp @@ -124,6 +125,8 @@ [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]: ../troubleshooting.md#debugging +[debugging]: https://github.com/Azure/autorest/blob/master/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 \ No newline at end of file +[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 \ No newline at end of file diff --git a/docs/generate/readme.md b/docs/generate/readme.md index 8f6864786..06982f565 100644 --- a/docs/generate/readme.md +++ b/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| |`--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| -|`--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| ## 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 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`: @@ -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 -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. @@ -345,15 +345,15 @@ The OpenAPI definitions for management plane code also live in the `resource-man ## 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 -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 -See [here](.flags.md) for a complete index of flags. +See [here][flags] for a complete index of flags. ## Generate from Private GitHub Repos @@ -382,17 +382,22 @@ For language-specific information about generation, please refer to our language - [C#][csharp] -[flags]: ./flags.md -[openapi_docs]: ../openapi/readme.md -[pets_swagger]: ../openapi/examples/pets.json -[basic_example]: ./examples/basic/readme.md -[pets_v2_swagger]: ./openapi/examples/pets.json -[tags_readme]: ./examples/tags/readme.md +[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 [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 -[python]: https://github.com/Azure/autorest.python/tree/autorestv3/docs/generate -[java]: https://github.com/Azure/autorest.java/tree/v4/docs/generate -[csharp]: https://github.com/Azure/autorest.csharp/tree/v3/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/readme.md +[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_java]: https://github.com/Azure/azure-sdk-for-java/tree/master/sdk \ No newline at end of file +[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 \ No newline at end of file diff --git a/docs/install/readme.md b/docs/install/readme.md index 6264e1081..6125658b2 100644 --- a/docs/install/readme.md +++ b/docs/install/readme.md @@ -1,4 +1,4 @@ -# Installing AutoRest +# Installing AutoRest 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. -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]. # 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 ``` -[troubleshooting]: ../troubleshooting.md#module-errors \ No newline at end of file +[troubleshooting]: ../troubleshooting.md#module-errors +[autorest_versioning]: ./autorest-versioning.md \ No newline at end of file diff --git a/docs/introduction.md b/docs/introduction.md index 853b3b183..21646d4c5 100644 --- a/docs/introduction.md +++ b/docs/introduction.md @@ -13,7 +13,7 @@ The main [swagger docs][swagger_basic_structure] have a good example for the bas ## 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. @@ -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_docs]: https://swagger.io/docs/ [openapi_docs]: ./openapi/readme.md -[landing_page]: readme.md \ No newline at end of file +[landing_page]: readme.md +[extensions]: extensions/readme.md \ No newline at end of file diff --git a/docs/migrate/readme.md b/docs/migrate/readme.md index 63401e34c..ae490676c 100644 --- a/docs/migrate/readme.md +++ b/docs/migrate/readme.md @@ -1,4 +1,4 @@ -# Migrating from AutoRest V2 to V3 +# Migrating from AutoRest V2 to V3 ## General Guidance 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 -[install]: ../install/readme.md -[language_flags]: generate/readme.md#language-flags +[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 [guidelines]: https://azure.github.io/azure-sdk/general_introduction.html -[python]: https://github.com/Azure/autorest.python/tree/autorestv3/docs/migrate -[java]: https://github.com/Azure/autorest.java/tree/v4/docs/migrate -[csharp]: https://github.com/Azure/autorest.csharp/tree/v3/docs/migrate -[typescript]: https://github.com/Azure/autorest.typescript/tree/v6/docs/migrate \ No newline at end of file +[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 +[csharp]: https://github.com/Azure/autorest.csharp/tree/v3/docs/migrate/readme.md +[typescript]: https://github.com/Azure/autorest.typescript/tree/v6/docs/migrate/readme.md \ No newline at end of file diff --git a/docs/readme.md b/docs/readme.md index 8ba54e217..afe066d06 100644 --- a/docs/readme.md +++ b/docs/readme.md @@ -24,18 +24,15 @@ 8. `Powershell` documentation - [How][powershell] do I use AutoRest to build `Powershell` cmdlets? -9. [FAQ][faq] - -10. [Troubleshooting][troubleshooting] +9. [Troubleshooting][troubleshooting] -[introduction]: ./introduction.md -[install]: ./install/readme.md -[openapi]: ./openapi/readme.md -[generate]: ./generate/readme.md -[client]: ./client/readme.md -[migrate]: ./migrate/readme.md -[dev]: ./developer/readme.md -[powershell]: ./powershell/readme.md -[faq]: ./faq.md -[troubleshooting]: ./troubleshooting.md \ No newline at end of file +[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 +[powershell]: https://github.com/Azure/autorest/blob/master/docs/powershell/readme.md +[troubleshooting]: https://github.com/Azure/autorest/blob/master/docs/troubleshooting.md \ No newline at end of file diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md index 3074626b4..0b01341eb 100644 --- a/docs/troubleshooting.md +++ b/docs/troubleshooting.md @@ -6,7 +6,7 @@ When running into an AutoRest issues actually running the AutoRest program, your ## 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. @@ -23,7 +23,7 @@ If you're error does not look like this, refer to the docs in our language gener - [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. ## Debugging @@ -38,12 +38,12 @@ If you would like to actually debug through a language generator's code, see our - [Typescript][typescript_debug] -[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_python_issues]: https://github.com/Azure/autorest.python/issues [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 -[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 [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