Skip to content

Commit 35f4729

Browse files
gerrytangerrytan
committed
Improvements to Microsoft.AzureTerraform TypeSpec
Based from .NET SDK review: 1. Use ArmOperationStatus from library instead of defining our own 2. Wrap both exportTerraform and operationStatuses operations in single ExportTerraform interface 3. Added client.tsp override so the generated method name for .NET SDK complies with the guidelines 4. Removed unecessary suppresses and DRY-ed response types
1 parent fda3d5e commit 35f4729

File tree

8 files changed

+112
-104
lines changed

8 files changed

+112
-104
lines changed

‎specification/terraform/Microsoft.AzureTerraform.Management/client.tsp‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
import "@azure-tools/typespec-client-generator-core";
2+
import "./main.tsp";
3+
4+
using Azure.ClientGenerator.Core;
5+
using Microsoft.AzureTerraform;
6+
7+
@@clientName(ExportTerraform.exportTerraform, "ExportTerraform", "csharp");
8+
@@clientName(ExportTerraform.operationStatuses, "OperationStatuses", "csharp");

‎specification/terraform/Microsoft.AzureTerraform.Management/examples/2023-07-01-preview/ExportTerraform.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
{
22
"title": "ExportTerraform",
3-
"operationId": "ExportTerraform",
3+
"operationId": "ExportTerraform_ExportTerraform",
44
"parameters": {
55
"api-version": "2023-07-01-preview",
66
"subscriptionId": "00000000-0000-0000-0000-000000000000",

‎specification/terraform/Microsoft.AzureTerraform.Management/examples/2023-07-01-preview/GetOperationStatus.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
{
22
"title": "Get specific operation status",
3-
"operationId": "OperationStatuses_Get",
3+
"operationId": "ExportTerraform_OperationStatuses",
44
"parameters": {
55
"subscriptionId": "00000000-0000-0000-0000-000000000000",
66
"operationId": "00000000-0000-0000-0000-000000000000",

‎specification/terraform/Microsoft.AzureTerraform.Management/models.tsp‎

Lines changed: 8 additions & 38 deletions
Original file line numberDiff line numberDiff line change
@@ -93,44 +93,14 @@ model ExportResourceGroup extends BaseExportModel {
9393
}
9494

9595
@doc("The status of the LRO operation.")
96-
model OperationStatus {
97-
@doc("The operation status resource id.")
98-
id?: string;
99-
100-
@doc("The fully qualified resource id of the resource for which the operation was performed.")
101-
@visibility("read")
102-
resourceId?: string;
103-
104-
@doc("The operation name.")
105-
name?: string;
106-
107-
@doc("The start time of the operation.")
108-
@visibility("read")
109-
startTime?: utcDateTime;
110-
111-
@doc("The end time of the operation.")
112-
@visibility("read")
113-
endTime?: utcDateTime;
114-
115-
@doc("The status of the operation.")
116-
status?: string;
117-
118-
@doc("The progress percentage of the operation, ranges from 0 to 100")
119-
percentComplete?: float64;
120-
121-
@doc("The Terraform export result")
122-
properties?: ExportResult;
123-
124-
...ErrorResponse;
125-
}
126-
127-
model InProgressOperationStatus
128-
is ArmAcceptedResponse<
129-
"InProgress operation status",
130-
ArmCombinedLroHeaders & Azure.Core.Foundations.RetryAfterHeader
131-
> {
132-
...OperationStatus;
133-
}
96+
model OperationStatus is ArmOperationStatus<ExportResult>;
97+
98+
model AcceptedLroResponse<Description extends valueof string>
99+
is ArmAcceptedLroResponse<
100+
Description,
101+
ArmCombinedLroHeaders<ArmOperationStatus, OperationStatus> &
102+
Azure.Core.Foundations.RetryAfterHeader
103+
>;
134104

135105
@doc("The Terraform export result")
136106
model ExportResult {

‎specification/terraform/Microsoft.AzureTerraform.Management/routes.tsp‎

Lines changed: 27 additions & 32 deletions
Original file line numberDiff line numberDiff line change
@@ -2,52 +2,47 @@ import "@azure-tools/typespec-azure-core";
22
import "@typespec/rest";
33
import "./models.tsp";
44
import "@azure-tools/typespec-azure-resource-manager";
5+
import "@azure-tools/typespec-client-generator-core";
56

67
using TypeSpec.Rest;
78
using TypeSpec.Http;
9+
using Azure.Core;
10+
using Azure.ClientGenerator.Core;
811
using Azure.ResourceManager;
912
using Azure.ResourceManager.Foundations;
1013
using OpenAPI;
1114

1215
namespace Microsoft.AzureTerraform;
1316

14-
#suppress "@azure-tools/typespec-azure-resource-manager/arm-resource-operation" "Cannot use @armResourceOperations decorator here, the auto-generated routes do not match feature requirements"
15-
#suppress "@azure-tools/typespec-azure-core/no-openapi" "TODO: migrate to LRO concepts DO NOT USE x-ms-long-running-operation-options"
16-
@doc("Exports the Terraform configuration of the specified resource(s).")
17-
@route("/subscriptions/{subscriptionId}/providers/Microsoft.AzureTerraform/exportTerraform")
18-
@post
19-
@tag("ExportTerraform")
20-
@extension(
21-
"x-ms-long-running-operation-options",
22-
{
23-
`final-state-via`: "azure-async-operation",
24-
`final-state-schema`: "#/definitions/OperationStatus",
25-
}
26-
)
27-
op exportTerraform(
28-
...ApiVersionParameter,
29-
...SubscriptionIdParameter,
17+
@doc("Parameters common to all ExportTerraform operations")
18+
model CommonExportTerraformParameters {
19+
...ApiVersionParameter;
20+
...SubscriptionIdParameter;
21+
}
22+
23+
#suppress "@azure-tools/typespec-azure-resource-manager/arm-resource-interface-requires-decorator" "Cannot use @armResourceOperations decorator, the implied @autoRoute forces {subscriptionId} path param to be at the end"
24+
interface ExportTerraform {
25+
#suppress "@azure-tools/typespec-azure-resource-manager/arm-resource-operation" "Cannot use @armResourceOperation, API is not bound to a single resource type"
26+
@doc("Exports the Terraform configuration of the specified resource(s).")
27+
@route("/subscriptions/{subscriptionId}/providers/Microsoft.AzureTerraform/exportTerraform")
28+
@post
29+
@tag("ExportTerraform")
30+
@pollingOperation(ExportTerraform.operationStatuses)
31+
exportTerraform(
32+
...CommonExportTerraformParameters,
3033

31-
@doc("The export parameter")
32-
@body
33-
exportParameter: BaseExportModel,
34-
): ArmAcceptedLroResponse<
35-
"Export request accepted.",
36-
ArmCombinedLroHeaders<ArmOperationStatus, OperationStatus> &
37-
Azure.Core.Foundations.RetryAfterHeader
38-
> | ErrorResponse;
34+
@doc("The export parameter")
35+
@body
36+
exportParameter: BaseExportModel,
37+
): AcceptedLroResponse<"Export request accepted."> | ErrorResponse;
3938

40-
#suppress "@azure-tools/typespec-azure-resource-manager/arm-resource-interface-requires-decorator" "Cannot use @armResourceOperations decorator here, the auto-generated routes do not match feature requirements"
41-
interface OperationStatuses {
42-
#suppress "@azure-tools/typespec-azure-resource-manager/no-response-body" "Body of 202 is not empty: not compatible with API requirements"
39+
#suppress "@azure-tools/typespec-azure-resource-manager/arm-resource-operation" "Cannot use @armResourceRead, API is not bound to a single resource type"
4340
@doc("Get the status of a long running azure asynchronous operation.")
4441
@route("/subscriptions/{subscriptionId}/providers/Microsoft.AzureTerraform/operationStatuses/{operationId}")
4542
@get
4643
@tag("OperationStatuses")
47-
@armResourceRead(ArmResponse<OperationStatus>)
48-
get(
44+
operationStatuses(
4945
...OperationIdParameter,
50-
...ApiVersionParameter,
51-
...SubscriptionIdParameter,
52-
): OperationStatus | InProgressOperationStatus | ErrorResponse;
46+
...CommonExportTerraformParameters,
47+
): OperationStatus | AcceptedLroResponse<"InProgress operation status"> | ErrorResponse;
5348
}

‎specification/terraform/resource-manager/Microsoft.AzureTerraform/preview/2023-07-01-preview/examples/ExportTerraform.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
{
22
"title": "ExportTerraform",
3-
"operationId": "ExportTerraform",
3+
"operationId": "ExportTerraform_ExportTerraform",
44
"parameters": {
55
"api-version": "2023-07-01-preview",
66
"subscriptionId": "00000000-0000-0000-0000-000000000000",

‎specification/terraform/resource-manager/Microsoft.AzureTerraform/preview/2023-07-01-preview/examples/GetOperationStatus.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
{
22
"title": "Get specific operation status",
3-
"operationId": "OperationStatuses_Get",
3+
"operationId": "ExportTerraform_OperationStatuses",
44
"parameters": {
55
"subscriptionId": "00000000-0000-0000-0000-000000000000",
66
"operationId": "00000000-0000-0000-0000-000000000000",

‎specification/terraform/resource-manager/Microsoft.AzureTerraform/preview/2023-07-01-preview/export.json‎

Lines changed: 65 additions & 30 deletions
Original file line numberDiff line numberDiff line change
@@ -40,10 +40,10 @@
4040
},
4141
"tags": [
4242
{
43-
"name": "ExportTerraform"
43+
"name": "Operations"
4444
},
4545
{
46-
"name": "Operations"
46+
"name": "ExportTerraform"
4747
},
4848
{
4949
"name": "OperationStatuses"
@@ -88,7 +88,7 @@
8888
},
8989
"/subscriptions/{subscriptionId}/providers/Microsoft.AzureTerraform/exportTerraform": {
9090
"post": {
91-
"operationId": "ExportTerraform",
91+
"operationId": "ExportTerraform_ExportTerraform",
9292
"tags": [
9393
"ExportTerraform"
9494
],
@@ -143,15 +143,14 @@
143143
}
144144
},
145145
"x-ms-long-running-operation-options": {
146-
"final-state-via": "azure-async-operation",
147-
"final-state-schema": "#/definitions/OperationStatus"
146+
"final-state-via": "location"
148147
},
149148
"x-ms-long-running-operation": true
150149
}
151150
},
152151
"/subscriptions/{subscriptionId}/providers/Microsoft.AzureTerraform/operationStatuses/{operationId}": {
153152
"get": {
154-
"operationId": "OperationStatuses_Get",
153+
"operationId": "ExportTerraform_OperationStatuses",
155154
"tags": [
156155
"OperationStatuses"
157156
],
@@ -176,9 +175,6 @@
176175
},
177176
"202": {
178177
"description": "InProgress operation status",
179-
"schema": {
180-
"$ref": "#/definitions/OperationStatus"
181-
},
182178
"headers": {
183179
"Azure-AsyncOperation": {
184180
"type": "string",
@@ -212,6 +208,42 @@
212208
}
213209
},
214210
"definitions": {
211+
"Azure.Core.uuid": {
212+
"type": "string",
213+
"format": "uuid",
214+
"description": "Universally Unique Identifier"
215+
},
216+
"Azure.ResourceManager.ResourceProvisioningState": {
217+
"type": "string",
218+
"description": "The provisioning state of a resource type.",
219+
"enum": [
220+
"Succeeded",
221+
"Failed",
222+
"Canceled"
223+
],
224+
"x-ms-enum": {
225+
"name": "ResourceProvisioningState",
226+
"modelAsString": true,
227+
"values": [
228+
{
229+
"name": "Succeeded",
230+
"value": "Succeeded",
231+
"description": "Resource has been created."
232+
},
233+
{
234+
"name": "Failed",
235+
"value": "Failed",
236+
"description": "Resource creation failed."
237+
},
238+
{
239+
"name": "Canceled",
240+
"value": "Canceled",
241+
"description": "Resource creation was canceled."
242+
}
243+
]
244+
},
245+
"readOnly": true
246+
},
215247
"BaseExportModel": {
216248
"type": "object",
217249
"description": "The base export parameter",
@@ -379,49 +411,52 @@
379411
"type": "object",
380412
"description": "The status of the LRO operation.",
381413
"properties": {
382-
"id": {
383-
"type": "string",
384-
"description": "The operation status resource id."
385-
},
386-
"resourceId": {
387-
"type": "string",
388-
"description": "The fully qualified resource id of the resource for which the operation was performed.",
414+
"properties": {
415+
"$ref": "#/definitions/ExportResult",
416+
"description": "RP-specific properties for the operationStatus resource, only appears when operation ended with Succeeded status",
389417
"readOnly": true
390418
},
419+
"status": {
420+
"$ref": "#/definitions/Azure.ResourceManager.ResourceProvisioningState",
421+
"description": "The operation status"
422+
},
423+
"id": {
424+
"$ref": "#/definitions/Azure.Core.uuid",
425+
"description": "The unique identifier for the operationStatus resource"
426+
},
391427
"name": {
392428
"type": "string",
393-
"description": "The operation name."
429+
"description": "The name of the operationStatus resource",
430+
"readOnly": true
394431
},
395432
"startTime": {
396433
"type": "string",
397434
"format": "date-time",
398-
"description": "The start time of the operation.",
435+
"description": "Operation start time",
399436
"readOnly": true
400437
},
401438
"endTime": {
402439
"type": "string",
403440
"format": "date-time",
404-
"description": "The end time of the operation.",
441+
"description": "Operation complete time",
405442
"readOnly": true
406443
},
407-
"status": {
408-
"type": "string",
409-
"description": "The status of the operation."
410-
},
411444
"percentComplete": {
412445
"type": "number",
413446
"format": "double",
414-
"description": "The progress percentage of the operation, ranges from 0 to 100"
415-
},
416-
"properties": {
417-
"$ref": "#/definitions/ExportResult",
418-
"description": "The Terraform export result"
447+
"description": "The progress made toward completing the operation",
448+
"readOnly": true
419449
},
420450
"error": {
421451
"$ref": "../../../../../common-types/resource-management/v5/types.json#/definitions/ErrorDetail",
422-
"description": "The error object."
452+
"description": "Errors that occurred if the operation ended with Canceled or Failed status",
453+
"readOnly": true
423454
}
424-
}
455+
},
456+
"required": [
457+
"status",
458+
"id"
459+
]
425460
},
426461
"Type": {
427462
"type": "string",

0 commit comments

Comments
 (0)