Overview

This is the next gen (v4) of AutoRest Java generator. It's built on AutoRest v3, written in Java, and supports OpenAPI3. It generates clients that work with com.azure:azure-core.

Prerequisites

You need to have the following installed on your machine:

• Node.JS v12+
• Java 11+
• Maven 3

You need to have autorest installed through NPM:

npm install -g autorest

Usage

To use the latest released preview (https://github.com/Azure/autorest.java/releases), run

autorest --java
    --use:@autorest/java@4.x.x
    --input-file:path/to/specs.json
    --output-folder:where/to/generate/java/files
    --namespace:specified.java.package

The first time running it will take a little longer to download and install all the components.

To build from source code, clone this repo and checkout to main branch. Make sure all prerequisites are met, and run

mvn package -P local

This will build a file javagen-jar-with-dependencies.jar under javagen module, a fluentgen-jar-with-dependencies.jar under fluentgen module.

And then run AutoRest

autorest --java
    --use:where/this/repo/is/cloned/autorest.java
    --input-file:path/to/specs.json
    --output-folder:where/to/generate/java/files
    --namespace:specified.java.package

Java files will be generated under where/to/generate/java/files/src/main/java/specified/java/package.

To debug, add --java.debugger to the argument list. The JVM will suspend at the beginning of the execution. Then attach a remote debugger in your IDE to localhost:5005. Make sure you detach the debugger before killing the AutoRest process. Otherwise it will fail to shut down the JVM and leave it orphaned. (which can be killed in the Task Manager)

Recommended Settings

• use-default-http-status-code-to-exception-type-mapping: true, use subclass of HttpResponseException defined in azure-core, when service returns unexpected status code.

• generic-response-type: true, use ResponseBase<>, instead a subclass of ResponseBase<>, for response with HTTP headers. Performance and reflective access improvement.

• no-custom-headers: true, generates overloads of interface methods that exclude typed headers. Performance improvement by removing the need to convert header strings to Java types.

• required-fields-as-ctor-args, create a constructor taking required properties, for model classes. The correctness of this constructor highly depends on the correctness of Swagger.

• output-model-immutable: true, make model classes immutable, if model is used only in response.

• enable-sync-stack: true, let sync method invoke sync RestProxy method.

• enable-page-size: true, let maxpagesize query parameter be supplied via byPage API in PagedFlux or PagedIterable.

• use-key-credential: true, use KeyCredential in builder for API key.

• generate-client-as-impl: true, generate Client in implementation package, for customization.

• models-subpackage: implementation.models, generate model classes in implementation package.

• custom-types-subpackage: models, generate selected model classes in models package.

Settings

Settings can be provided on the command line through --name:value or in a README file through name: value. The list of settings for AutoRest in general can be found at https://github.com/Azure/autorest/blob/main/docs/user/command-line-interface.md. The list of settings for AutoRest.Java specifically are listed below:

|Option  | Description | |------------------|-------------| |--client-side-validations|Generate validations for required parameters and required model properties. Default is false.| |--generate-client-as-impl|Append "Impl" to the names of service clients and method groups and place them in the implementation sub-package. Default is false.| |--generate-client-interfaces|Implies --generate-client-as-impl and generates interfaces for all the "Impl"s. Default is false.| |--generate-sync-async-clients|Implies --generate-client-as-impl and generates sync and async convenience layer clients for all the "Impl"s. Default is false.| |--generate-builder-per-client|Requires --generate-sync-async-clients, and generates one ClientBuilder for each Client. Default is false.| |--implementation-subpackage=STRING|The sub-package that the Service client and Method Group client implementation classes will be put into. Default is implementation.| |--models-subpackage=STRING|The sub-package that Enums, Exceptions, and Model types will be put into. Default is models.| |--sync-methods=all\|essential\|none|Specifies mode for generating sync wrappers. Supported value are <br>  essential - generates only one sync returning body or header (default) <br>  all - generates one sync method for each async method<br>  none - does not generate any sync methods| |--required-parameter-client-methods|Indicates whether client method overloads with only required parameters should be generated. Default is false.| |--custom-types=COMMA,SEPARATED,STRINGS|Specifies a list of files to put in the package specified in --custom-types-subpackage.| |--custom-types-subpackage=STRING|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.modelsto generate models to implementation.models by default and pick specific models to be public through --custom-types=.| |--client-type-prefix=STRING|The prefix that will be added to each generated client type.| |--service-interface-as-public|Indicates whether to generate service interfaces as public. This resolves SecurityManager issues to prevent reflectively access non-public APIs. Default is true.| |--client-flattened-annotation-target=TYPE,FIELD,NONE,DISABLED|Indicates the target of @JsonFlatten annotation for x-ms-client-flatten. Default is TYPE.| |--disable-client-builder|Indicates whether to disable generating the ClientBuilder class. This is for SDK that already contains a hand-written ClientBuilder class. Default is false.| |--polling|Configures how to generate long running operations. See Polling Configuration to see more details on how to use this flag.| |--service-name|Service name used in Client class and other documentations. If not provided, service name is deduced from title configure (from swagger or readme).| |--partial-update|Indicates whether to support partial update for Client/AsyncClient classes and ClientBuilder class.| |--default-http-exception-type|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.| |--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.| |--generic-response-type|Indicates that generic response types are used instead of named response types that extend the generic type.| |--no-custom-headers|Indicates that overloads of interface methods that exclude typed headers are generated.| |--enable-sync-stack|Indicates that sync method invokes sync RestProxy method. By default, sync method invokes async RestProxy method.| |--required-fields-as-ctor-args|Indicates that class models have constructor taking required properties.| |--output-model-immutable|Indicates that output-only models be generated as immutable, and without public constructor.| |--use-input-stream-for-binary|Indicates that InputStream is used for binary response body. By default, BinaryData is used.| |--enable-page-size|Indicates that maxpagesize query parameter be supplied via byPage API in PagedFlux or PagedIterable, instead of via client method parameter.| |--use-key-credential|Indicates that builder uses KeyCredential for API key.| |--graal-vm-config|Generates GraalVM config under resources/META-INF/native-image.| |--rename-model|CSV. Rename classes. Each item is of pattern from:to.|

Settings for minimal data-plane clients

data-plane option enables the generator to generate code for minimal data-plane clients.

data-plane option will change the default value for some vanilla options. For example, generate-client-interfaces, generate-client-as-impl, generate-sync-async-clients, generate-builder-per-client, enable-sync-stack, required-fields-as-ctor-args option is by default true. polling is by default enabled as default settings globally (polling={}).

sdk-integration option can be used for integrating to azure-sdk-for-java.

generate-samples option can be used for generating samples for client. generate-tests option can be used for generating tests for client.

See documentation for frequently used options, and their effect on generated clients.

Additional settings for Fluent

fluent option enables the generator extension for Azure Management Libraries for Java.

Following settings only works when fluent option is specified.

| Option | Description | | ----------- | ----------- | | --fluent | Enum. LITE for Fluent Lite; PREMIUM for Fluent Premium. Case insensitive. Default is PREMIUM if provided as other values. | | --fluent-subpackage | String. The sub-package that vanilla client and builder will be put into. Default is fluent. | | --pom-file | S