Skip to content

Commit 323d870

Browse files
gerrytangerrytan
committed
TypeSpec for Microsoft.AzureTerraform (Azure#19390)
* TypeSpec for Microsoft.AzureTerraform * Sorted swagger file, and added typespec generated with tsp-client * revert export.json in prep of merging * Sorted export.json for easy diff on future typespec -> swagger * Rerun swagger -> typespec conversion after merging latest RPSaaSMaster, updated namespace * tsp compile for TypeSpec -> swagger * Refactored typescript to minimise swagger diff * Spread ErrorResponse into OperationStatus model * Fixed enums, use doc decorator * Update exportTerraform path desc * Update doc for ExportResource model * LintDiff fix: remove unnecessary auth * Add resourceId prop to OperationStatus model, fixed char casing so they're consistent throughout * Made resourceId read only * Check `Swagger BreakingChange`: minimise diff on x-ms-enum * TypeSpec Validation fix: rename dir and add missing @doc
1 parent d2b1a69 commit 323d870

File tree

11 files changed

+564
-193
lines changed

11 files changed

+564
-193
lines changed

‎specification/terraform/.gitignore‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
# Override the **/terraform/** rule set at the top level to avoid relevant files getting ignored
2+
!**/*.json

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

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
{
2+
"title": "ExportTerraform",
3+
"operationId": "ExportTerraform",
4+
"parameters": {
5+
"api-version": "2023-07-01-preview",
6+
"subscriptionId": "00000000-0000-0000-0000-000000000000",
7+
"exportParameter": {
8+
"type": "ExportResourceGroup",
9+
"resourceGroupName": "rg1"
10+
}
11+
},
12+
"responses": {
13+
"202": {
14+
"headers": {
15+
"Azure-AsyncOperation": "https://management.azure.com/subscriptions/00000000-0000-0000-0000-000000000000/providers/Microsoft.AzureTerraform/operationStatus/00000000-0000-0000-0000-000000000000?api-version=2023-07-01-preview",
16+
"Location": "https://management.azure.com/subscriptions/00000000-0000-0000-0000-000000000000/providers/Microsoft.AzureTerraform/operationStatus/00000000-0000-0000-0000-000000000000?api-version=2023-07-01-preview"
17+
}
18+
}
19+
}
20+
}

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

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
{
2+
"title": "Get specific operation status",
3+
"operationId": "OperationStatuses_Get",
4+
"parameters": {
5+
"subscriptionId": "00000000-0000-0000-0000-000000000000",
6+
"operationId": "00000000-0000-0000-0000-000000000000",
7+
"api-version": "2023-07-01-preview"
8+
},
9+
"responses": {
10+
"200": {
11+
"headers": {},
12+
"body": {
13+
"id": "https://management.azure.com/subscriptions/00000000-0000-0000-0000-000000000000/providers/Microsoft.AzureTerraform/operationStatus/00000000-0000-0000-0000-000000000000?api-version=2023-07-01-preview",
14+
"name": "00000000-0000-0000-0000-000000000000",
15+
"startTime": "2024-07-08T08:48:46.3160075Z",
16+
"endTime": "2024-07-08T08:49:23.7083Z",
17+
"status": "Succeeded",
18+
"properties": {
19+
"configuration": "resource \"azurerm_resource_group\" \"res-0\" {\n location = \"westeurope\"\n name = \"rg1\"\n}",
20+
"errors": null,
21+
"skippedResources": null
22+
}
23+
}
24+
},
25+
"202": {
26+
"headers": {
27+
"Azure-AsyncOperation": "https://management.azure.com/subscriptions/00000000-0000-0000-0000-000000000000/providers/Microsoft.AzureTerraform/operationStatus/00000000-0000-0000-0000-000000000000?api-version=2023-07-01-preview",
28+
"Location": "https://management.azure.com/subscriptions/00000000-0000-0000-0000-000000000000/providers/Microsoft.AzureTerraform/operationStatus/00000000-0000-0000-0000-000000000000?api-version=2023-07-01-preview"
29+
},
30+
"body": {
31+
"id": "https://management.azure.com/subscriptions/00000000-0000-0000-0000-000000000000/providers/Microsoft.AzureTerraform/operationStatus/00000000-0000-0000-0000-000000000000?api-version=2023-07-01-preview",
32+
"name": "00000000-0000-0000-0000-000000000000",
33+
"startTime": "2024-07-08T08:48:46.3160075Z",
34+
"status": "InProgress"
35+
}
36+
}
37+
}
38+
}

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

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
{
2+
"title": "Get a list of operations for a resource provider",
3+
"operationId": "Operations_List",
4+
"parameters": {
5+
"subscriptionId": "12345678-1234-1234-12345678abc",
6+
"api-version": "2023-07-01-preview"
7+
},
8+
"responses": {
9+
"200": {
10+
"body": {
11+
"value": [
12+
{
13+
"name": "Microsoft.AzureTerraform/operations/read",
14+
"display": {
15+
"provider": "Microsoft AzureTerraform",
16+
"resource": "Azure Terraform Resource Provider",
17+
"operation": "ListOperations",
18+
"description": "Lists all of the available RP operations."
19+
}
20+
},
21+
{
22+
"name": "Microsoft.AzureTerraform/exportTerraform/action",
23+
"display": {
24+
"provider": "Microsoft AzureTerraform",
25+
"resource": "Azure Terraform Resource Provider",
26+
"operation": "ExportTerraform",
27+
"description": "Exports the Terraform configuration used for the specified scope."
28+
}
29+
}
30+
]
31+
}
32+
}
33+
}
34+
}

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

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
/**
2+
* PLEASE DO NOT REMOVE - USED FOR CONVERTER METRICS
3+
* Generated by package: @autorest/openapi-to-typespec
4+
* Version: 0.9.0
5+
* Date: 2024-08-30T14:24:13.436Z
6+
*/
7+
import "@typespec/rest";
8+
import "@typespec/versioning";
9+
import "@azure-tools/typespec-azure-core";
10+
import "@azure-tools/typespec-azure-resource-manager";
11+
import "./models.tsp";
12+
import "./routes.tsp";
13+
14+
using TypeSpec.Rest;
15+
using TypeSpec.Http;
16+
using Azure.ResourceManager.Foundations;
17+
using Azure.Core;
18+
using Azure.ResourceManager;
19+
using TypeSpec.Versioning;
20+
21+
@doc("The Azure Terraform management API provides a RESTful set of web services that used to manage your Azure Terraform resources.")
22+
@armProviderNamespace
23+
@service({
24+
title: "AzureTerraformResourceProviderClient",
25+
})
26+
@versioned(Versions)
27+
@armCommonTypesVersion(Azure.ResourceManager.CommonTypes.Versions.v5)
28+
namespace Microsoft.AzureTerraform;
29+
30+
@doc("The available API versions.")
31+
enum Versions {
32+
@doc("The 2023-07-01-preview API version.")
33+
@useDependency(Azure.ResourceManager.Versions.v1_0_Preview_1)
34+
@useDependency(Azure.Core.Versions.v1_0_Preview_1)
35+
v2023_07_01_preview: "2023-07-01-preview",
36+
}

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

Lines changed: 160 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,160 @@
1+
import "@typespec/rest";
2+
import "@typespec/http";
3+
import "@azure-tools/typespec-azure-resource-manager";
4+
5+
using TypeSpec.Rest;
6+
using TypeSpec.Http;
7+
using Azure.ResourceManager;
8+
using Azure.ResourceManager.Foundations;
9+
using OpenAPI;
10+
11+
namespace Microsoft.AzureTerraform;
12+
13+
interface Operations extends Azure.ResourceManager.Operations {}
14+
15+
@doc("The parameter type")
16+
@extension(
17+
"x-ms-enum",
18+
{
19+
name: "parameterType",
20+
modelAsString: true,
21+
}
22+
)
23+
union Type {
24+
string,
25+
ExportResource: "ExportResource",
26+
ExportResourceGroup: "ExportResourceGroup",
27+
ExportQuery: "ExportQuery",
28+
}
29+
30+
@doc("The target Azure Terraform Provider")
31+
@extension(
32+
"x-ms-enum",
33+
{
34+
name: "targetProvider",
35+
modelAsString: true,
36+
}
37+
)
38+
union targetProvider {
39+
string,
40+
41+
@doc("https://registry.terraform.io/providers/hashicorp/azurerm/latest")
42+
azurerm: "azurerm",
43+
44+
@doc("https://registry.terraform.io/providers/Azure/azapi/latest")
45+
azapi: "azapi",
46+
}
47+
48+
@doc("The base export parameter")
49+
@discriminator("type")
50+
model BaseExportModel {
51+
@doc("The parameter type")
52+
type: Type;
53+
54+
@doc("The target Azure Terraform Provider")
55+
targetProvider?: targetProvider = targetProvider.azurerm;
56+
57+
@doc("Whether to output all non-computed properties in the generated Terraform configuration? This probably needs manual modifications to make it valid")
58+
fullProperties?: boolean = true;
59+
60+
@doc("Mask sensitive attributes in the Terraform configuration")
61+
maskSensitive?: boolean = true;
62+
}
63+
64+
@doc("Export parameter for resources queried by ARG (Azure Resource Graph)")
65+
model ExportQuery extends BaseExportModel {
66+
@doc("The ARG where predicate. Note that you can combine multiple conditions in one `where` predicate, e.g. `resourceGroup =~ \"my-rg\" and type =~ \"microsoft.network/virtualnetworks\"`")
67+
query: string;
68+
69+
@doc("The name pattern of the Terraform resources")
70+
namePattern?: string = "res-";
71+
72+
@doc("Whether to recursively list child resources of the query result")
73+
recursive?: boolean = false;
74+
75+
@doc("The parameter type")
76+
type: "ExportQuery";
77+
}
78+
79+
@doc("Export parameter for individual resources.")
80+
model ExportResource extends BaseExportModel {
81+
@doc("The id of the resource to be exported")
82+
resourceIds: string[];
83+
84+
@doc("The Terraform resource name. Only works when `resourceIds` contains only one item.")
85+
resourceName?: string = "res-0";
86+
87+
@doc("The Terraform resource type. Only works when `resourceIds` contains only one item.")
88+
resourceType?: string;
89+
90+
@doc("The name pattern of the Terraform resources")
91+
namePattern?: string = "res-";
92+
93+
@doc("The parameter type")
94+
type: "ExportResource";
95+
}
96+
97+
@doc("Export parameter for a resource group")
98+
model ExportResourceGroup extends BaseExportModel {
99+
@doc("The name of the resource group to be exported")
100+
resourceGroupName: string;
101+
102+
@doc("The name pattern of the Terraform resources")
103+
namePattern?: string = "res-";
104+
105+
@doc("The parameter type")
106+
type: "ExportResourceGroup";
107+
}
108+
109+
@doc("The status of the LRO operation.")
110+
model OperationStatus {
111+
@doc("The operation status resource id.")
112+
id?: string;
113+
114+
@doc("The fully qualified resource id of the resource for which the operation was performed.")
115+
@visibility("read")
116+
resourceId?: string;
117+
118+
@doc("The operation name.")
119+
name?: string;
120+
121+
@doc("The start time of the operation.")
122+
@visibility("read")
123+
startTime?: utcDateTime;
124+
125+
@doc("The end time of the operation.")
126+
@visibility("read")
127+
endTime?: utcDateTime;
128+
129+
@doc("The status of the operation.")
130+
status?: string;
131+
132+
@doc("The progress percentage of the operation, ranges from 0 to 100")
133+
percentComplete?: float64;
134+
135+
@doc("The Terraform export result")
136+
properties?: ExportResult;
137+
138+
...ErrorResponse;
139+
}
140+
141+
model InProgressOperationStatus
142+
is ArmAcceptedResponse<
143+
"InProgress operation status",
144+
ArmCombinedLroHeaders & Azure.Core.Foundations.RetryAfterHeader
145+
> {
146+
...OperationStatus;
147+
}
148+
149+
@doc("The Terraform export result")
150+
model ExportResult {
151+
@doc("The Terraform configuration content")
152+
configuration?: string;
153+
154+
@doc("A list of Azure resources which are not exported to Terraform due to there is no corresponding resources in Terraform")
155+
skippedResources?: string[];
156+
157+
@doc("A list of errors derived during exporting each resource")
158+
@extension("x-ms-identifiers", [])
159+
errors?: ErrorDetail[];
160+
}

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

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
1+
import "@azure-tools/typespec-azure-core";
2+
import "@typespec/rest";
3+
import "./models.tsp";
4+
import "@azure-tools/typespec-azure-resource-manager";
5+
6+
using TypeSpec.Rest;
7+
using TypeSpec.Http;
8+
using Azure.ResourceManager;
9+
using Azure.ResourceManager.Foundations;
10+
using OpenAPI;
11+
12+
namespace Microsoft.AzureTerraform;
13+
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+
@doc("Exports the Terraform configuration of the specified resource(s).")
16+
@route("/subscriptions/{subscriptionId}/providers/Microsoft.AzureTerraform/exportTerraform")
17+
@post
18+
@tag("ExportTerraform")
19+
@extension(
20+
"x-ms-long-running-operation-options",
21+
{
22+
`final-state-via`: "azure-async-operation",
23+
`final-state-schema`: "#/definitions/OperationStatus",
24+
}
25+
)
26+
op exportTerraform(
27+
...ApiVersionParameter,
28+
...SubscriptionIdParameter,
29+
30+
@doc("The export parameter")
31+
@body
32+
@extension("x-ms-parameter-location", "method")
33+
exportParameter: BaseExportModel,
34+
): ArmAcceptedLroResponse<
35+
"Export request accepted.",
36+
ArmCombinedLroHeaders & Azure.Core.Foundations.RetryAfterHeader
37+
> | ErrorResponse;
38+
39+
#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"
40+
interface OperationStatuses {
41+
#suppress "@azure-tools/typespec-azure-resource-manager/no-response-body" "Body of 202 is not empty: not compatible with API requirements"
42+
@doc("Get the status of a long running azure asynchronous operation.")
43+
@route("/subscriptions/{subscriptionId}/providers/Microsoft.AzureTerraform/operationStatuses/{operationId}")
44+
@get
45+
@tag("OperationStatuses")
46+
@armResourceRead(ArmResponse<OperationStatus>)
47+
get(
48+
...OperationIdParameter,
49+
...ApiVersionParameter,
50+
...SubscriptionIdParameter,
51+
): OperationStatus | InProgressOperationStatus | ErrorResponse;
52+
}

‎specification/terraform/Microsoft.AzureTerraform.Management/tspconfig.yaml‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
emit:
2+
- "@azure-tools/typespec-autorest"
3+
options:
4+
"@azure-tools/typespec-autorest":
5+
use-read-only-status-schema: true
6+
omit-unreachable-types: true
7+
emitter-output-dir: "{project-root}/.."
8+
azure-resource-provider-folder: "resource-manager"
9+
output-file: "{azure-resource-provider-folder}/{service-name}/{version-status}/{version}/export.json"
10+
examples-directory: "{project-root}/examples"
11+
linter:
12+
extends:
13+
- "@azure-tools/typespec-azure-rulesets/resource-manager"

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

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,6 @@
11
{
2+
"title": "Get specific operation status",
3+
"operationId": "OperationStatuses_Get",
24
"parameters": {
35
"subscriptionId": "00000000-0000-0000-0000-000000000000",
46
"operationId": "00000000-0000-0000-0000-000000000000",

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

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
{
2-
"title": "List Operations",
2+
"title": "Get a list of operations for a resource provider",
33
"operationId": "Operations_List",
44
"parameters": {
55
"subscriptionId": "12345678-1234-1234-12345678abc",

0 commit comments

Comments
 (0)