@autorest/java 4.1.18
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE.md +21 -0
- package/androidgen/README.md +30 -0
- package/androidgen/package.json +27 -0
- package/androidgen/target/azure-autorest-androidgen-jar-with-dependencies.jar +0 -0
- package/customization-base/README.md +720 -0
- package/docs/readme.md +34 -0
- package/fluentgen/package.json +26 -0
- package/fluentgen/readme.md +25 -0
- package/fluentgen/target/azure-autorest-fluentgen-jar-with-dependencies.jar +0 -0
- package/fluentnamer/package.json +26 -0
- package/fluentnamer/readme.md +65 -0
- package/fluentnamer/target/azure-autorest-fluentnamer-jar-with-dependencies.jar +0 -0
- package/javagen/package.json +26 -0
- package/javagen/readme.md +29 -0
- package/javagen/target/azure-autorest-javagen-jar-with-dependencies.jar +0 -0
- package/package.json +45 -0
- package/postprocessor/package.json +26 -0
- package/postprocessor/readme.md +9 -0
- package/postprocessor/target/azure-autorest-postprocessor-jar-with-dependencies.jar +0 -0
- package/preprocessor/data-plane.md +21 -0
- package/preprocessor/package.json +26 -0
- package/preprocessor/readme.md +62 -0
- package/preprocessor/target/azure-autorest-preprocessor-jar-with-dependencies.jar +0 -0
- package/readme.md +450 -0
- package/typespec-extension/package.json +75 -0
- package/typespec-extension/readme.md +148 -0
- package/typespec-tests/package.json +29 -0
- package/typespec-tests/readme.md +38 -0
package/readme.md
ADDED
|
@@ -0,0 +1,450 @@
|
|
|
1
|
+
# Overview
|
|
2
|
+
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`.
|
|
3
|
+
|
|
4
|
+
# Prerequisites
|
|
5
|
+
You need to have the following installed on your machine:
|
|
6
|
+
|
|
7
|
+
- Node.JS v12+
|
|
8
|
+
- Java 11+
|
|
9
|
+
- Maven 3
|
|
10
|
+
|
|
11
|
+
You need to have [autorest](https://www.npmjs.com/package/autorest) installed through NPM:
|
|
12
|
+
|
|
13
|
+
```bash
|
|
14
|
+
npm install -g autorest
|
|
15
|
+
```
|
|
16
|
+
|
|
17
|
+
# Usage
|
|
18
|
+
To use the latest released preview(https://github.com/Azure/autorest.java/releases), run
|
|
19
|
+
```bash
|
|
20
|
+
autorest --java
|
|
21
|
+
--use:@autorest/java@4.x.x
|
|
22
|
+
--input-file:path/to/specs.json
|
|
23
|
+
--output-folder:where/to/generate/java/files
|
|
24
|
+
--namespace:specified.java.package
|
|
25
|
+
```
|
|
26
|
+
The first time running it will take a little longer to download and install all the components.
|
|
27
|
+
|
|
28
|
+
To build from source code, clone this repo and checkout to main branch. Make sure all prerequisites are met, and run
|
|
29
|
+
|
|
30
|
+
```bash
|
|
31
|
+
mvn package -P local
|
|
32
|
+
```
|
|
33
|
+
|
|
34
|
+
This will build a file `javagen-jar-with-dependencies.jar` under `javagen` module, a `preprocess-jar-with-dependencies.jar` under `preprocessor` module, a `fluentgen-jar-with-dependencies.jar` under `fluentgen` module, and a `fluentnamer-jar-with-dependencies.jar` under `fluentnamer` module.
|
|
35
|
+
|
|
36
|
+
And then run AutoRest
|
|
37
|
+
|
|
38
|
+
```bash
|
|
39
|
+
autorest --java
|
|
40
|
+
--use:where/this/repo/is/cloned/autorest.java
|
|
41
|
+
--input-file:path/to/specs.json
|
|
42
|
+
--output-folder:where/to/generate/java/files
|
|
43
|
+
--namespace:specified.java.package
|
|
44
|
+
```
|
|
45
|
+
|
|
46
|
+
Java files will be generated under `where/to/generate/java/files/src/main/java/specified/java/package`.
|
|
47
|
+
|
|
48
|
+
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 shutdown the JVM and leave it orphaned. (which can be killed in the Task Manager)**
|
|
49
|
+
|
|
50
|
+
# Recommended Settings
|
|
51
|
+
|
|
52
|
+
- `use-default-http-status-code-to-exception-type-mapping: true`, use subclass of `HttpResponseException` defined in azure-core, when service returns unexpected status code.
|
|
53
|
+
- `generic-response-type: true`, use `ResponseBase<>`, instead a subclass of `ResponseBase<>`, for response with HTTP headers. Performance and reflective access improvement.
|
|
54
|
+
- `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.
|
|
55
|
+
- `output-model-immutable: true`, make model classes immutable, if model is used only in response.
|
|
56
|
+
- `enable-sync-stack: true`, let sync method invoke sync RestProxy method.
|
|
57
|
+
|
|
58
|
+
- `generate-client-as-impl: true`, generate Client in implementation package, for customization.
|
|
59
|
+
- `models-subpackage: implementation.models`, generate model classes in implementation package.
|
|
60
|
+
- `custom-types-subpackage: models`, generate selected model classes in models package.
|
|
61
|
+
|
|
62
|
+
# Settings
|
|
63
|
+
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:
|
|
64
|
+
|
|
65
|
+
|Option | Description |
|
|
66
|
+
|------------------|-------------|
|
|
67
|
+
|`--enable-xml`|Generates models and clients that can be sent in XML over the wire. Default is false|
|
|
68
|
+
|`--client-side-validations`|Generate validations for required parameters and required model properties. Default is false.|
|
|
69
|
+
|`--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.|
|
|
70
|
+
|`--generate-client-interfaces`|Implies `--generate-client-as-impl` and generates interfaces for all the "Impl"s. Default is false.|
|
|
71
|
+
|`--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.|
|
|
72
|
+
|`--generate-builder-per-client`| Requires `--generate-sync-async-clients`, and generates one ClientBuilder for each Client. Default is false.|
|
|
73
|
+
|`--implementation-subpackage=STRING`|The sub-package that the Service client and Method Group client implementation classes will be put into. Default is `implementation`.|
|
|
74
|
+
|`--models-subpackage=STRING`|The sub-package that Enums, Exceptions, and Model types will be put into. Default is `models`.|
|
|
75
|
+
|`--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|
|
|
76
|
+
|`--required-parameter-client-methods`|Indicates whether client method overloads with only required parameters should be generated. Default is false.|
|
|
77
|
+
|`--custom-types=COMMA,SEPARATED,STRINGS`|Specifies a list of files to put in the package specified in `--custom-types-subpackage`.|
|
|
78
|
+
|`--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.models`to generate models to `implementation.models` by default and pick specific models to be public through `--custom-types=`.|
|
|
79
|
+
|`--client-type-prefix=STRING`|The prefix that will be added to each generated client type.|
|
|
80
|
+
|`--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.|
|
|
81
|
+
|`--require-x-ms-flattened-to-flatten`|Indicates whether `x-ms-flattened` is required to annotated a class with `@JsonFlatten` if the discriminator has `.` in its name. Default is false.|
|
|
82
|
+
|`--client-flattened-annotation-target=TYPE,FIELD,NONE`|Indicates the target of `@JsonFlatten` annotation for `x-ms-client-flatten`. Default is `TYPE`. If value is `FIELD`, it implies `require-x-ms-flattened-to-flatten=true`.|
|
|
83
|
+
|`--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.|
|
|
84
|
+
|`--skip-formatting`|Indicates whether to skip formatting Java file. Default is false.|
|
|
85
|
+
|`--polling`|Configures how to generate long running operations. See [Polling Configuration](#polling-configuration) to see more details on how to use this flag.|
|
|
86
|
+
|`--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).|
|
|
87
|
+
|`--partial-update`|Indicates whether to support partial update for `Client`/`AsyncClient` classes and `ClientBuilder` class.|
|
|
88
|
+
|`--pass-discriminator-to-child-deserialization`|Indicates whether the discriminator property is passed to subclass deserialization. Default is false.|
|
|
89
|
+
|`--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`.|
|
|
90
|
+
|`--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.|
|
|
91
|
+
|`--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`.|
|
|
92
|
+
|`--generic-response-type`|Indicates that generic response types are used instead of named response types that extend the generic type.|
|
|
93
|
+
|`--enable-sync-stack`|Indicates that sync method invokes sync RestProxy method. By default, sync method invokes async RestProxy method.|
|
|
94
|
+
|`--required-fields-as-ctor-args`|Indicates that class models have constructor taking required properties.|
|
|
95
|
+
|`--output-model-immutable`|Indicates that output-only models be generated as immutable, and without public constructor.|
|
|
96
|
+
|`--use-input-stream-for-binary`|Indicates that `InputStream` is used for binary response body. By default, `BinaryData` is used.|
|
|
97
|
+
|
|
98
|
+
## Settings for minimal data-plane clients
|
|
99
|
+
|
|
100
|
+
`data-plane` option enables the generator to generate code for minimal data-plane clients.
|
|
101
|
+
|
|
102
|
+
`data-plane` option will change the default value for some vanilla options.
|
|
103
|
+
For example, `generate-client-interfaces`, `generate-client-as-impl`, `generate-sync-async-clients`, `generate-builder-per-client` option is by default `true`.
|
|
104
|
+
`polling` is by default enabled as default settings globally (`polling={}`).
|
|
105
|
+
|
|
106
|
+
`sdk-integration` option can be used for integrating to [azure-sdk-for-java](https://github.com/Azure/azure-sdk-for-java/).
|
|
107
|
+
|
|
108
|
+
`generate-samples` option can be used for generating samples for client.
|
|
109
|
+
`generate-tests` option can be used for generating tests for client.
|
|
110
|
+
`generate-models` option can be used for generating models.
|
|
111
|
+
|
|
112
|
+
See [documentation](docs/generate/dataplane.md) for frequently used options, and their effect on generated clients.
|
|
113
|
+
|
|
114
|
+
## Additional settings for Fluent
|
|
115
|
+
|
|
116
|
+
`fluent` option enables the generator extension for [Azure Management Libraries for Java](https://aka.ms/azsdk/java/mgmt).
|
|
117
|
+
|
|
118
|
+
Following settings only works when `fluent` option is specified.
|
|
119
|
+
|
|
120
|
+
| Option | Description |
|
|
121
|
+
| ----------- | ----------- |
|
|
122
|
+
| `--fluent` | Enum. `LITE` for Fluent Lite; `PREMIUM` for Fluent Premium. Case insensitive. Default is `PREMIUM` if provided as other values. |
|
|
123
|
+
| `--fluent-subpackage` | String. The sub-package that vanilla client and builder will be put into. Default is `fluent`. |
|
|
124
|
+
| `--pom-file` | String. Name for Maven POM file. Default is `pom.xml`. |
|
|
125
|
+
| `--package-version` | String. Version number for Maven artifact. Default is `1.0.0-beta.1`. |
|
|
126
|
+
| `--service-name` | String. Service name used in Manager class and other documentations. If not provided, service name is deduced from `title` configure (from swagger or readme). |
|
|
127
|
+
| `--sdk-integration` | Boolean. Integrate to [azure-sdk-for-java](https://github.com/Azure/azure-sdk-for-java/). Default is `false`. Provide `output-folder` as absolute path for best performance. |
|
|
128
|
+
| `--generate-samples` | Boolean. Generate samples from `x-ms-examples` in swagger. Default is `false`. |
|
|
129
|
+
| `--add-inner` | CSV. Treat as inner class (move to `fluent.models` namespace, append `Inner` to class name). |
|
|
130
|
+
| `--remove-inner` | CSV. Exclude from inner classes. |
|
|
131
|
+
| `--rename-model` | CSV. Rename classes. Each item is of pattern `from:to`. |
|
|
132
|
+
| `--remove-model` | CSV. Remove classes. |
|
|
133
|
+
| `--preserve-model` | CSV. Preserve classes from clean-up. |
|
|
134
|
+
| `--remove-operation-group` | CSV. Remove operation groups. |
|
|
135
|
+
| `--name-for-ungrouped-operations` | String. Name for ungrouped operation group. Default to `ResourceProviders` for Lite. |
|
|
136
|
+
|
|
137
|
+
`fluent` option will change the default value for some vanilla options.
|
|
138
|
+
For example, `generate-client-interfaces`, `required-parameter-client-methods` option is by default `true`.
|
|
139
|
+
|
|
140
|
+
The code formatter would require Java 11+ runtime.
|
|
141
|
+
|
|
142
|
+
## Polling configuration
|
|
143
|
+
Polling configurations can be set through `--polling` setting globally or for each operation. The format is a key value map specified below:
|
|
144
|
+
|
|
145
|
+
```
|
|
146
|
+
polling:
|
|
147
|
+
{operationId}:
|
|
148
|
+
strategy: {strategy}
|
|
149
|
+
intermediate-type: {intermediate-type}
|
|
150
|
+
final-type: {final-type}
|
|
151
|
+
poll-interval: {poll-interval}
|
|
152
|
+
```
|
|
153
|
+
|
|
154
|
+
With the fields specified below:
|
|
155
|
+
|
|
156
|
+
|Field|Type|Required|Description|Example|
|
|
157
|
+
|-----|----|--------|-----------|-------|
|
|
158
|
+
|operationId|String|true|The `operationId` of the operation. For global polling configuration, use `default`. Case insensitive.|`Pets_put`|
|
|
159
|
+
|strategy|String|false|The invocation to construct a polling strategy. Use fully qualified class name if outside the implementation subpackage specified in `namespace` & `implementation-subpackage`. Use dynamic literals `{httpPipeline}`, `{context}`, `{serializerAdapter}`, `{intermediate-type}`, `{final-type}` if these components are required to construct the polling strategy. Default is `new DefaultPollingStrategy<>(new PollingStrategyOptions({httpPipeline}).setEndpoint({endpoint}).setContext({context}))`.|`new com.azure.core.util.polling.OperationResourcePollingStrategy<>({httpPipeline}, {context})`|
|
|
160
|
+
|intermediate-type|String|false|The type of the polling intermediate type. Use fully qualified class name if outside the base package specified in `namespace`. Default is the return type specified on the operation in Swagger, or `BinaryData` if the operation returns `void`.|`PollResult`,`com.azure.core.util.BinaryData`|
|
|
161
|
+
|final-type|String|false|The type of the final result type. Use fully qualified class name if outside the base package specified in `namespace`. Default is the return type specified on the operation in Swagger, or `BinaryData` if the operation returns `void`.|`Pet`,`com.azure.core.util.BinaryData`|
|
|
162
|
+
|poll-interval|integer|false|The default interval in seconds to poll with (can be modified by users in `PollerFlux` and `SyncPoller`. Default is 1.|30|
|
|
163
|
+
|
|
164
|
+
To use default settings globally, use `--polling={}`.
|
|
165
|
+
|
|
166
|
+
## HTTP Status Code to Exception Type Handling
|
|
167
|
+
|
|
168
|
+
By default, Swagger definitions will contain an exception type to be thrown when any error HTTP status code is seen. Swaggers
|
|
169
|
+
may also define the error HTTP status code to exception type mapping, but isn't always the case. Or, it may be needed to change
|
|
170
|
+
the default exception type to a custom type. In these cases it is possible to configure the error HTTP status code to exception
|
|
171
|
+
type handling by using the configurations `--default-http-exception-type`, `--use-default-http-status-code-to-exception-type-mapping`,
|
|
172
|
+
and `--http-status-code-to-exception-type-mapping`.
|
|
173
|
+
|
|
174
|
+
NOTE: Using the configurations on an already shipped library will likely result in runtime breaking changes as most
|
|
175
|
+
libraries are already using a sub-class type of `HttpResponseException` and changing sub-types is a breaking change.
|
|
176
|
+
|
|
177
|
+
### Default Http Exception Type
|
|
178
|
+
|
|
179
|
+
The default exception type is used for all error HTTP response status codes that do not have an explicit exception type
|
|
180
|
+
configured. Generally, there is no error HTTP response status code to exception type mapping, so this will become your
|
|
181
|
+
general exception type. The following is an example of configuring `com.azure.core.exception.HttpResponseException` as
|
|
182
|
+
the default exception type:
|
|
183
|
+
|
|
184
|
+
`autorest --default-http-exception-type=com.azure.core.exception.HttpResponseException`
|
|
185
|
+
|
|
186
|
+
or in the Swagger README configuration:
|
|
187
|
+
|
|
188
|
+
```
|
|
189
|
+
default-http-exception-type: com.azure.core.exception.HttpResponseException
|
|
190
|
+
```
|
|
191
|
+
|
|
192
|
+
If this configuration isn't used the default exception type will be based on the Swagger definition.
|
|
193
|
+
|
|
194
|
+
### Use Default HTTP Status Code to Exception Type Mapping
|
|
195
|
+
|
|
196
|
+
The default error HTTP status code to exception type map is the following:
|
|
197
|
+
|
|
198
|
+
|Status Code|Exception Type|
|
|
199
|
+
|-----------|--------------|
|
|
200
|
+
|401|com.azure.core.exception.ClientAuthenticationException|
|
|
201
|
+
|404|com.azure.core.exception.ResourceNotFoundException|
|
|
202
|
+
|409|com.azure.core.exception.ResourceModifiedException|
|
|
203
|
+
|
|
204
|
+
By default, this mapping isn't used, to use it pass the `--use-default-http-status-code-to-exception-type-mapping` to
|
|
205
|
+
the generator or in the Swagger README configuration:
|
|
206
|
+
|
|
207
|
+
```
|
|
208
|
+
use-default-http-status-code-to-exception-type-mapping: true
|
|
209
|
+
```
|
|
210
|
+
|
|
211
|
+
### Custom HTTP Status Code to Exception Type Mapping
|
|
212
|
+
|
|
213
|
+
If you need to have a custom mapping it is possible to do so by using `--http-status-code-to-exception-type-mapping`.
|
|
214
|
+
This requires additional configuration in the Swagger README definition as it is a mapping of HTTP status code to
|
|
215
|
+
exception. The following is an example:
|
|
216
|
+
|
|
217
|
+
```
|
|
218
|
+
http-status-code-to-exception-type-mapping:
|
|
219
|
+
404: com.azure.core.exception.ResourceNotFoundException
|
|
220
|
+
412: com.azure.core.exception.ResourceExistsException
|
|
221
|
+
```
|
|
222
|
+
|
|
223
|
+
### Example
|
|
224
|
+
|
|
225
|
+
The HTTP status code to exception type handling configurations can be used together to offer a nice baseline default
|
|
226
|
+
with additional customizations as need. For example, if you wanted to configure the default exception type, use most of
|
|
227
|
+
the default error HTTP status code to exception type, and customize one error HTTP status code exception type the following
|
|
228
|
+
configurations can be used.
|
|
229
|
+
|
|
230
|
+
```
|
|
231
|
+
default-http-exception-type: com.azure.core.exception.HttpResponseException
|
|
232
|
+
use-default-http-status-code-to-exception-type-mapping: true
|
|
233
|
+
http-status-code-to-exception-type-mapping:
|
|
234
|
+
404: com.azure.core.exception.ResourceExistsException
|
|
235
|
+
```
|
|
236
|
+
|
|
237
|
+
This results in the following error HTTP response to exception type mapping:
|
|
238
|
+
|
|
239
|
+
|Status Code|Exception Type|
|
|
240
|
+
|-----------|--------------|
|
|
241
|
+
|401|com.azure.core.exception.ClientAuthenticationException|
|
|
242
|
+
|404|com.azure.core.exception.ResourceExistsException|
|
|
243
|
+
|409|com.azure.core.exception.ResourceModifiedException|
|
|
244
|
+
|*|com.azure.core.exception.HttpResponseException|
|
|
245
|
+
|
|
246
|
+
Notices how 404 changes from the default `com.azure.core.exception.ResourceNotFoundException` to
|
|
247
|
+
`com.azure.core.exception.ResourceExistsException`.
|
|
248
|
+
|
|
249
|
+
# Minimal Data-Plane Clients
|
|
250
|
+
|
|
251
|
+
You can generate the output as minimal data-plane clients with `--data-plane` flag.
|
|
252
|
+
The models will not be generated and the methods in the clients will be generated as [protocol methods](https://github.com/Azure/azure-sdk-for-java/wiki/Protocol-Methods).
|
|
253
|
+
|
|
254
|
+
The generated code has the following structure:
|
|
255
|
+
|
|
256
|
+
```
|
|
257
|
+
- pom.xml
|
|
258
|
+
- /src/main/java
|
|
259
|
+
|
|
|
260
|
+
- module-info.java
|
|
261
|
+
- /com/azure/<group>/<service>
|
|
262
|
+
|
|
|
263
|
+
- <Service>Builder.java
|
|
264
|
+
- <Service>Client.java
|
|
265
|
+
- <Service>AsyncClient.java
|
|
266
|
+
- /implementation
|
|
267
|
+
|
|
|
268
|
+
- <Service>ClientImpl.java
|
|
269
|
+
```
|
|
270
|
+
|
|
271
|
+
and requires latest `azure-core` as a dependency.
|
|
272
|
+
|
|
273
|
+
# Customizations
|
|
274
|
+
|
|
275
|
+
For guidance on using the post-code generation customization framework see its [documentation](https://github.com/Azure/autorest.java/tree/main/customization-base/README.md).
|
|
276
|
+
|
|
277
|
+
# Project structure
|
|
278
|
+
## extension-base
|
|
279
|
+
This contains the base classes and utilities for creating an AutoRest extension in Java. It handles the JSON RPC communications with AutoRest core, provides JSON and YAML parsers, and provides the POJO models for the code model output from [modelerfour](https://github.com/Azure/autorest.modelerfour/).
|
|
280
|
+
|
|
281
|
+
Extend from `NewPlugin.java` class if you are writing a new extension in Java.
|
|
282
|
+
|
|
283
|
+
## javagen
|
|
284
|
+
This contains the actual generator extension, including mappers that maps a code model to a Java client model, and templates that writes the Java client models into .java files.
|
|
285
|
+
|
|
286
|
+
## fluentgen
|
|
287
|
+
This contains the [generator extension for Azure Management Libraries](#additional-settings-for-fluent).
|
|
288
|
+
|
|
289
|
+
## tests
|
|
290
|
+
This contains the generated classes from the [test swaggers](https://github.com/Azure/autorest.testserver/tree/main/swagger) in `src/main`. The code here should always be kept up-to-date with the output of the generator in `javagen`.
|
|
291
|
+
|
|
292
|
+
This also contains test code for these generated code under `src/test`. Running the tests will hit the test server running locally (see https://github.com/Azure/autorest.testserver for instructions) and verify the correctness of the generated code.
|
|
293
|
+
|
|
294
|
+
# Contributing
|
|
295
|
+
|
|
296
|
+
This project welcomes contributions and suggestions. Most contributions require you to agree to a
|
|
297
|
+
Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us
|
|
298
|
+
the rights to use your contribution. For details, visit https://cla.microsoft.com.
|
|
299
|
+
|
|
300
|
+
When you submit a pull request, a CLA-bot will automatically determine whether you need to provide
|
|
301
|
+
a CLA and decorate the PR appropriately (e.g., label, comment). Simply follow the instructions
|
|
302
|
+
provided by the bot. You will only need to do this once across all repos using our CLA.
|
|
303
|
+
|
|
304
|
+
This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/).
|
|
305
|
+
For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or
|
|
306
|
+
contact [opencode@microsoft.com](mailto:opencode@microsoft.com) with any additional questions or comments.
|
|
307
|
+
|
|
308
|
+
### Autorest plugin configuration
|
|
309
|
+
- Please don't edit this section unless you're re-configuring how the Java extension plugs in to AutoRest
|
|
310
|
+
AutoRest needs the below config to pick this up as a plug-in - see https://github.com/Azure/autorest/blob/main/docs/developer/architecture/AutoRest-extension.md
|
|
311
|
+
|
|
312
|
+
#### Javagen
|
|
313
|
+
|
|
314
|
+
``` yaml $(java) && !$(fluent) && !$(android)
|
|
315
|
+
use: $(this-folder)/javagen
|
|
316
|
+
```
|
|
317
|
+
|
|
318
|
+
``` yaml $(java) && $(fluent) && !$(android)
|
|
319
|
+
use: $(this-folder)/fluentgen
|
|
320
|
+
```
|
|
321
|
+
|
|
322
|
+
``` yaml $(java) && $(android)
|
|
323
|
+
use: $(this-folder)/androidgen
|
|
324
|
+
```
|
|
325
|
+
|
|
326
|
+
#### Help
|
|
327
|
+
|
|
328
|
+
```yaml
|
|
329
|
+
help-content:
|
|
330
|
+
java:
|
|
331
|
+
activationScope: java
|
|
332
|
+
categoryFriendlyName: Java Generator
|
|
333
|
+
settings:
|
|
334
|
+
- key: enable-xml
|
|
335
|
+
type: bool
|
|
336
|
+
description: Generates models and clients that can be sent in XML over the wire. Default is false
|
|
337
|
+
- key: client-side-validations
|
|
338
|
+
type: bool
|
|
339
|
+
description: Generate validations for required parameters and required model properties. Default is false.
|
|
340
|
+
- key: generate-client-as-impl
|
|
341
|
+
type: bool
|
|
342
|
+
description: Append "Impl" to the names of service clients and method groups and place them in the `implementation` sub-package. Default is false.
|
|
343
|
+
- key: generate-client-interfaces
|
|
344
|
+
type: bool
|
|
345
|
+
description: Implies `--generate-client-as-impl` and generates interfaces for all the "Impl"s. Default is false.
|
|
346
|
+
- key: generate-sync-async-clients
|
|
347
|
+
type: bool
|
|
348
|
+
description: Implies `--generate-client-as-impl` and generates sync and async convenience layer clients for all the "Impl"s. Default is false.
|
|
349
|
+
- key: generate-builder-per-client
|
|
350
|
+
type: bool
|
|
351
|
+
description: Requires `--generate-sync-async-clients`, and generates one ClientBuilder for each Client. Default is false.
|
|
352
|
+
- key: implementation-subpackage=STRING
|
|
353
|
+
type: string
|
|
354
|
+
description: The sub-package that the Service client and Method Group client implementation classes will be put into. Default is `implementation`.
|
|
355
|
+
- key: models-subpackage=STRING
|
|
356
|
+
type: string
|
|
357
|
+
description: The sub-package that Enums, Exceptions, and Model types will be put into. Default is `models`.
|
|
358
|
+
- key: sync-methods
|
|
359
|
+
type: string
|
|
360
|
+
description: \[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
|
|
361
|
+
- key: required-parameter-client-methods
|
|
362
|
+
type: bool
|
|
363
|
+
description: Indicates whether client method overloads with only required parameters should be generated. Default is false.
|
|
364
|
+
- key: custom-types
|
|
365
|
+
type: string
|
|
366
|
+
description: \[COMMA,SEPARATED,STRINGS] Specifies a list of files to put in the package specified in `--custom-types-subpackage`.
|
|
367
|
+
- key: custom-types-subpackage
|
|
368
|
+
type: string
|
|
369
|
+
description: 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=`.
|
|
370
|
+
- key: client-type-prefix
|
|
371
|
+
type: string
|
|
372
|
+
description: The prefix that will be added to each generated client type.
|
|
373
|
+
- key: client-flattened-annotation-target
|
|
374
|
+
type: string
|
|
375
|
+
description: \[TYPE,FIELD] Indicates the target of `@JsonFlatten` annotation for `x-ms-client-flatten`. Default is `TYPE`. If value is `FIELD`, it implies `require-x-ms-flattened-to-flatten=true`.
|
|
376
|
+
- key: disable-client-builder
|
|
377
|
+
type: bool
|
|
378
|
+
description: Indicates whether to disable generating the `ClientBuilder` class. This is for SDK that already contains a hand-written `ClientBuilder` class. Default is false.
|
|
379
|
+
- key: skip-formatting
|
|
380
|
+
type: bool
|
|
381
|
+
description: Indicates whether to skip formatting Java file. Default is false.
|
|
382
|
+
- key: polling
|
|
383
|
+
type: string
|
|
384
|
+
description: Configures how to generate long running operations. See [Polling Configuration](https://github.com/Azure/autorest.java#polling-configuration) to see more details on how to use this flag.
|
|
385
|
+
- key: service-name
|
|
386
|
+
type: string
|
|
387
|
+
description: Service name used in Client class and other documentations. If not provided, service name is deduced from `title` configure (from swagger or readme).
|
|
388
|
+
- key: partial-update
|
|
389
|
+
type: bool
|
|
390
|
+
description: Indicates whether to support partial update for `Client`/`AsyncClient` classes and `ClientBuilder` class. Default is false.
|
|
391
|
+
- key: enable-sync-stack
|
|
392
|
+
type: bool
|
|
393
|
+
description: Indicates that sync method invokes sync RestProxy method. By default, sync method invokes async RestProxy method.
|
|
394
|
+
- key: required-fields-as-ctor-args
|
|
395
|
+
type: bool
|
|
396
|
+
description: Indicates that class models have constructor taking required properties.
|
|
397
|
+
- key: output-model-immutable
|
|
398
|
+
type: bool
|
|
399
|
+
description: Indicates that output-only models be generated as immutable, and without public constructor. Default is false.
|
|
400
|
+
- key: data-plane
|
|
401
|
+
type: bool
|
|
402
|
+
description: Indicates whether to generate code for minimal clients. Default is false.
|
|
403
|
+
|
|
404
|
+
javafluent:
|
|
405
|
+
activationScope: fluent
|
|
406
|
+
categoryFriendlyName: Java fluent Generator
|
|
407
|
+
settings:
|
|
408
|
+
- key: fluent
|
|
409
|
+
type: string
|
|
410
|
+
description: Enum. `LITE` for Fluent Lite; `PREMIUM` for Fluent Premium. Case insensitive. Default is `PREMIUM` if provided as other values.
|
|
411
|
+
- key: fluent-subpackage
|
|
412
|
+
type: string
|
|
413
|
+
description: String. The sub-package that vanilla client and builder will be put into. Default is `fluent`.
|
|
414
|
+
- key: pom-file
|
|
415
|
+
type: string
|
|
416
|
+
description: String. Name for Maven POM file. Default is `pom.xml`.
|
|
417
|
+
- key: package-version
|
|
418
|
+
type: string
|
|
419
|
+
description: String. Version number for Maven artifact. Default is `1.0.0-beta.1`.
|
|
420
|
+
- key: service-name
|
|
421
|
+
type: string
|
|
422
|
+
description: String. Service name used in Manager class and other documentations. If not provided, service name is deduced from `title` configure (from swagger or readme).
|
|
423
|
+
- key: sdk-integration
|
|
424
|
+
type: bool
|
|
425
|
+
description: Boolean. Integrate to [azure-sdk-for-java](https://github.com/Azure/azure-sdk-for-java/). Default is `false`. Provide `output-folder` as absolute path for best performance.
|
|
426
|
+
- key: generate-samples
|
|
427
|
+
type: bool
|
|
428
|
+
description: Boolean. Generate samples from `x-ms-examples` in swagger. Default is `false`.
|
|
429
|
+
- key: add-inner
|
|
430
|
+
type: string
|
|
431
|
+
description: CSV. Treat as inner class (move to `fluent.models` namespace, append `Inner` to class name).
|
|
432
|
+
- key: remove-inner
|
|
433
|
+
type: string
|
|
434
|
+
description: CSV. Exclude from inner classes.
|
|
435
|
+
- key: rename-model
|
|
436
|
+
type: string
|
|
437
|
+
description: CSV. Rename classes. Each item is of pattern `from:to`.
|
|
438
|
+
- key: remove-model
|
|
439
|
+
type: string
|
|
440
|
+
description: CSV. Remove classes.
|
|
441
|
+
- key: preserve-model
|
|
442
|
+
type: string
|
|
443
|
+
description: CSV. Preserve classes from clean-up.
|
|
444
|
+
- key: remove-operation-group
|
|
445
|
+
type: string
|
|
446
|
+
description: CSV. Remove operation groups.
|
|
447
|
+
- key: name-for-ungrouped-operations
|
|
448
|
+
type: string
|
|
449
|
+
description: String. Name for ungrouped operation group. Default to `ResourceProviders` for Lite.
|
|
450
|
+
```
|
|
@@ -0,0 +1,75 @@
|
|
|
1
|
+
{
|
|
2
|
+
"name": "@azure-tools/typespec-java",
|
|
3
|
+
"version": "0.8.5",
|
|
4
|
+
"description": "TypeSpec library for emitting Java client from the TypeSpec REST protocol binding",
|
|
5
|
+
"keywords": [
|
|
6
|
+
"TypeSpec"
|
|
7
|
+
],
|
|
8
|
+
"author": "Microsoft Corporation",
|
|
9
|
+
"homepage": "https://github.com/Azure/autorest.java",
|
|
10
|
+
"readme": "https://github.com/Azure/autorest.java/blob/main/typespec-extension/readme.md",
|
|
11
|
+
"repository": {
|
|
12
|
+
"type": "git",
|
|
13
|
+
"url": "git+https://github.com/Azure/autorest.java.git"
|
|
14
|
+
},
|
|
15
|
+
"bugs": {
|
|
16
|
+
"url": "https://github.com/Azure/autorest.java/issues"
|
|
17
|
+
},
|
|
18
|
+
"license": "MIT",
|
|
19
|
+
"type": "module",
|
|
20
|
+
"main": "dist/src/emitter.js",
|
|
21
|
+
"exports": {
|
|
22
|
+
".": "./dist/src/emitter.js",
|
|
23
|
+
"./testing": "./dist/src/testing/index.js"
|
|
24
|
+
},
|
|
25
|
+
"tspMain": "dist/src/emitter.js",
|
|
26
|
+
"engines": {
|
|
27
|
+
"node": ">=14.0.0"
|
|
28
|
+
},
|
|
29
|
+
"scripts": {
|
|
30
|
+
"clean": "rimraf ./dist ./temp",
|
|
31
|
+
"build": "tsc -p .",
|
|
32
|
+
"watch": "tsc -p . --watch",
|
|
33
|
+
"test": "mocha",
|
|
34
|
+
"test-official": "c8 mocha --forbid-only",
|
|
35
|
+
"lint": "eslint . --ext .ts --max-warnings=0",
|
|
36
|
+
"lint:fix": "eslint . --fix --ext .ts",
|
|
37
|
+
"format": "npm run -s prettier -- --write",
|
|
38
|
+
"check-format": "npm run prettier -- --check",
|
|
39
|
+
"prettier": "prettier --config ./.prettierrc.yaml **/*.ts"
|
|
40
|
+
},
|
|
41
|
+
"files": [
|
|
42
|
+
"lib/*.tsp",
|
|
43
|
+
"dist/**",
|
|
44
|
+
"!dist/test/**",
|
|
45
|
+
"target/azure-typespec-extension-jar-with-dependencies.jar"
|
|
46
|
+
],
|
|
47
|
+
"peerDependencies": {
|
|
48
|
+
"@typespec/compiler": ">=0.45.0 <1.0.0",
|
|
49
|
+
"@typespec/rest": ">=0.45.0 <1.0.0",
|
|
50
|
+
"@typespec/openapi": ">=0.45.0 <1.0.0",
|
|
51
|
+
"@typespec/versioning": ">=0.45.0 <1.0.0",
|
|
52
|
+
"@azure-tools/typespec-azure-core": ">=0.31.0 <1.0.0",
|
|
53
|
+
"@azure-tools/typespec-client-generator-core": ">=0.31.0 <1.0.0"
|
|
54
|
+
},
|
|
55
|
+
"dependencies": {
|
|
56
|
+
"@autorest/codemodel": "~4.19.3",
|
|
57
|
+
"lodash": "~4.17.21",
|
|
58
|
+
"js-yaml": "~4.1.0"
|
|
59
|
+
},
|
|
60
|
+
"devDependencies": {
|
|
61
|
+
"@types/lodash": "~4.14.195",
|
|
62
|
+
"@types/js-yaml": "~4.0.5",
|
|
63
|
+
"@types/mocha": "~10.0.1",
|
|
64
|
+
"@types/node": "~20.4.0",
|
|
65
|
+
"@types/prettier": "~2.7.3",
|
|
66
|
+
"c8": "~8.0.0",
|
|
67
|
+
"eslint": "~8.44.0",
|
|
68
|
+
"mocha": "~10.2.0",
|
|
69
|
+
"rimraf": "~5.0.1",
|
|
70
|
+
"typescript": "~5.1.6",
|
|
71
|
+
"@typescript-eslint/parser": "~5.61.0",
|
|
72
|
+
"@typescript-eslint/eslint-plugin": "~5.61.0",
|
|
73
|
+
"eslint-plugin-deprecation": "~1.4.1"
|
|
74
|
+
}
|
|
75
|
+
}
|