From 539078b009dbbdc0f3e030ba3b1d8e93cb188cef Mon Sep 17 00:00:00 2001 From: Weidong Xu Date: Tue, 31 May 2022 22:46:41 +0800 Subject: [PATCH] Update flags.md for Java (#4541) --- .prettierignore | 3 ++ docs/generate/flags.md | 72 ++++++++++++++++++++++++------------------ 2 files changed, 44 insertions(+), 31 deletions(-) diff --git a/.prettierignore b/.prettierignore index 5343c52c8..c70a74b32 100644 --- a/.prettierignore +++ b/.prettierignore @@ -334,3 +334,6 @@ packages/libs/codemodel/.resources **/test/scenarios/expected/**/*.yaml **/test/scenarios/expected/**/*.json packages/extensions/core/test/plugins/*/expected/*.json + +# MICROSOFT SECURITY.md +/SECURITY.md diff --git a/docs/generate/flags.md b/docs/generate/flags.md index 09b9acf84..a7414e682 100644 --- a/docs/generate/flags.md +++ b/docs/generate/flags.md @@ -106,7 +106,7 @@ The flags listed here are still provisional. Code generated with these flags can | ------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `--version-tolerant` | Whether you want to generate with our newer generator. The goal of this generator's generated code is to be more Pythonic, and to be tolerant to non-breaking version changes on the service side. This flag is still in preview, defaults to `false`. | | `--low-level-client` | Whether you want to generate an SDK with only request builders and a `send_request` method on the client. Defaults to `false`. | -| `—-models-mode=msrest\|none` | Whether you want models for your SDK or not. Currently we only generate `msrest` models if models are wanted. Defaults to `msrest` for current AutoRest generation, and `none` for `low-level-client` and `version-tolerant` generations. | +| `--models-mode=msrest\|none` | Whether you want models for your SDK or not. Currently we only generate `msrest` models if models are wanted. Defaults to `msrest` for current AutoRest generation, and `none` for `low-level-client` and `version-tolerant` generations. | | `--show-send-request` | Whether you want the `send_request` method on your client to be public or not. Defaults to `true` for `version-tolerant` and `low-level-client` generations. | | `--builders-visibility=public\|hidden\|embedded` | How visible you want your request builders to be. With `public`, you get a public rest layer with your request builders. With `private`, you still get a separate layer with your request builders, but it is hidden. Finally, with `embedded`, you get the builders embedded in your operations files. Defaults to `public` for `low-level-client`, `embedded` for others. | | `--show-operations` | Whether to generate operations for your client and operation groups. Defaults to `true` for non-`low-level-client` generations. | @@ -122,32 +122,39 @@ The flags listed here are still provisional. Code generated with these flags can ## 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
  `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`. | -| `--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 | +| ---------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `--java-sdks-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. | +| `--data-plane` | Enables Java's DPG, generating a minimal data-plane client. See [the java docs][java_exception] for details. | +| `--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
  `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=NAME` | 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=NAME(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`. **Recommended usage**: Set to `true`. | +| `--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=NAME` | The name of your project jar without its version. See [here][artifact_id] for more information about an artifact id. | +| `--polling` | The configuration on the generation of long running operations. See [the java docs][java_polling] for details. | +| `--default-http-exception-type=NAME` | The fully-qualified class name that should be used as the default HTTP exception type. The class must extend from `HttpResponseException`. | +| `--use-default-http-status-code-to-exception-type-mapping` | Indicates whether a default HTTP status code to exception mapping should be used if one isn't provided. Defaults to `false`. **Recommended usage**: Set to `true`. | +| `--http-status-code-to-exception-type-mapping` | The HTTP status code to exception mapping that should be used. All exception types must be fully-qualified and extend from `HttpResponseException`. See [the java docs][java_exception] for details. | +| `--custom-strongly-typed-header-deserialization` | Indicates whether strongly-typed HTTP header objects will use custom desrialization instead of Jackson Databind's convertValue method, providing substantial performance benefits. Defaults to `false`. **Recommended usage**: Set to `true`. | +| `--generic-response-type` | Indicates that generic response types are used instead of named response types that extend the generic type. Defaults to `false`. | +| `--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. | +| `--skip-formatting` | Indicates whether to skip formatting Java file. Defaults to `false`. **Recommended usage**: Set to `true` for diagnosis, when AutoRest fails due to syntax error in generated Java code. | ## TypeScript Flags @@ -190,8 +197,8 @@ The flags listed here are still provisional. Code generated with these flags can -[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 +[tracing_quickstart]: https://github.com/Azure/azure-sdk-for-python/blob/main/sdk/core/azure-core-tracing-opentelemetry/README.md +[azure_sdk_for_python]: https://github.com/Azure/azure-sdk-for-python/tree/main/sdk [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/main/docs/generate/readme.md#generating-multi-api-code @@ -201,11 +208,14 @@ The flags listed here are still provisional. Code generated with these flags can [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 -[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/main/sdk [pom]: https://maven.apache.org/guides/introduction/introduction-to-the-pom.html#what-is-a-pom -[java_context]: https://azuresdkdocs.blob.core.windows.net/$web/java/azure-core/1.0.0/index.html?com/azure/core/util/Context.html +[java_context]: https://azuresdkdocs.blob.core.windows.net/$web/java/azure-core/latest/com/azure/core/util/Context.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 +[java_polling]: https://github.com/Azure/autorest.java#polling-configuration +[java_exception]: https://github.com/Azure/autorest.java#http-status-code-to-exception-type-handling +[java_dpg]: https://github.com/Azure/autorest.java#settings-for-minimal-data-plane-clients [armcore_connection]: https://github.com/Azure/azure-sdk-for-go/blob/main/sdk/azcore/arm/connection.go [debugging]: https://github.com/Azure/autorest/blob/main/docs/troubleshooting.md#debugging [black]: https://pypi.org/project/black/