@azure-tools/typespec-azure-resource-manager 0.27.0 → 0.28.0-dev.1

package/lib/operations.tsp

@@ -7,6 +7,11 @@ using Azure.ResourceManager.Foundations;
 namespace Azure.ResourceManager;
 
 // OPERATION TEMPLATES
+
+/**
+ * A resource list operation, at the subscription scope
+ * @param TResource the resource being patched
+ */
 @autoRoute
 @doc("List {name} resources by subscription ID", TResource)
 @list(TResource)
@@ -17,6 +22,10 @@ op ArmListBySubscription<TResource extends ArmResource>(
   ...SubscriptionScope<TResource>
 ): ArmResponse<ResourceListResult<TResource>> | ErrorResponse;
 
+/**
+ * A resource list operation, at the scope of the resource's parent
+ * @param TResource the resource being patched
+ */
 @get
 @autoRoute
 @list(TResource)
@@ -32,6 +41,11 @@ op ArmResourceListByParent<
   ...ResourceParentParameters<TResource, TBaseParameters>
 ): ArmResponse<ResourceListResult<TResource>> | ErrorResponse;
 
+/**
+ * A resource list operation, with scope determined by TBaseParameters
+ * @param TResource the resource being patched
+ * @param TBaseParameters Optional. Allows overriding the operation parameters
+ */
 @get
 @autoRoute
 @list(TResource)
@@ -45,6 +59,11 @@ op ArmResourceListAtScope<
   ...ResourceParentParameters<TResource, TBaseParameters>
 ): ArmResponse<ResourceListResult<TResource>> | ErrorResponse;
 
+/**
+ * A resource GET operation
+ * @param TResource the resource being patched
+ * @param TBaseParameters Optional. Allows overriding the operation parameters
+ */
 @autoRoute
 @doc("Get a {name}", TResource)
 @get
@@ -53,6 +72,11 @@ op ArmResourceRead<TResource extends ArmResource, TBaseParameters = BaseParamete
   ...ResourceInstanceParameters<TResource, TBaseParameters>
 ): ArmResponse<TResource> | ErrorResponse;
 
+/**
+ * A long-running resource CreateOrUpdate (PUT)
+ * @param TResource the resource being patched
+ * @param TBaseParameters Optional. Allows overriding the operation parameters
+ */
 @autoRoute
 @doc("Create a {name}", TResource)
 @extension("x-ms-long-running-operation", true)
@@ -75,6 +99,11 @@ op ArmResourceCreateOrUpdateAsync<
   resource: TResource
 ): ArmResponse<TResource> | ArmCreatedResponse<TResource> | ErrorResponse;
 
+/**
+ * A resource CreateOrUpdate (PUT)
+ * @param TResource the resource being patched
+ * @param TBaseParameters Optional. Allows overriding the operation parameters
+ */
 @autoRoute
 @doc("Create a {name}", TResource)
 @armResourceCreateOrUpdate(TResource)
@@ -90,25 +119,42 @@ op ArmResourceCreateOrUpdateSync<
   resource: TResource
 ): ArmResponse<TResource> | ErrorResponse;
 
+/**
+ * A long-running resource update that only allows updating resource tags (the minimum)
+ * @param TResource the resource being patched
+ * @param TBaseParameters Optional. Allows overriding the operation parameters
+ */
 alias ArmTagsPatchAsync<
   TResource extends ArmResource,
   TProperties extends object,
   TBaseParameters = BaseParameters<TResource>
 > = ArmCustomPatchAsync<TResource, TagsUpdateModel<TResource>, TBaseParameters>;
 
+/**
+ * A long-running resource update using the items from the resource marked with visibility "update"
+ * @param TResource the resource being patched
+ * @param TProperties The model type of the resource properties
+ * @param TBaseParameters Optional. Allows overriding the operation parameters
+ */
 alias ArmResourcePatchAsync<
   TResource extends ArmResource,
   TProperties extends object,
   TBaseParameters = BaseParameters<TResource>
 > = ArmCustomPatchAsync<TResource, ResourceUpdateModel<TResource, TProperties>, TBaseParameters>;
 
+/**
+ * A long-running resource update using a custom PATCH payload (Asynchronous)
+ * @param TResource the resource being patched
+ * @param TPatchModel The input model for the PATCH request
+ * @param TBaseParameters Optional. Allows overriding the operation parameters
+ */
 @autoRoute
 @doc("Update a {name}", TResource)
 @extension("x-ms-long-running-operation", true)
 @extension(
   "x-ms-long-running-operation-options",
   {
-    `final-state-via`: "azure-async-operation",
+    `final-state-via`: "location",
   }
 )
 @armResourceUpdate(TResource)
@@ -123,19 +169,36 @@ op ArmCustomPatchAsync<
   @doc("The resource properties to be updated.")
   @body
   properties: TPatchModel
-): ArmResponse<TResource> | ArmAcceptedResponse<"Resource update request accepted."> | ErrorResponse;
+): ArmResponse<TResource> | ArmAcceptedLroResponse<"Resource update request accepted."> | ErrorResponse;
 
+/**
+ * A resource update that only allows updating resource tags (the minimum)
+ * @param TResource the resource being patched
+ * @param TBaseParameters Optional. Allows overriding the operation parameters
+ */
 alias ArmTagsPatchSync<
   TResource extends ArmResource,
   TBaseParameters = BaseParameters<TResource>
 > = ArmCustomPatchSync<TResource, TagsUpdateModel<TResource>, TBaseParameters>;
 
+/**
+ * A resource update using the items from the resource marked with visibility "update"
+ * @param TResource the resource being patched
+ * @param TProperties The model type of the resource properties
+ * @param TBaseParameters Optional. Allows overriding the operation parameters
+ */
 alias ArmResourcePatchSync<
   TResource extends ArmResource,
   TProperties extends object,
   TBaseParameters = BaseParameters<TResource>
 > = ArmCustomPatchSync<TResource, ResourceUpdateModel<TResource, TProperties>, TBaseParameters>;
 
+/**
+ * A resource update using a custom PATCH payload (synchronous)
+ * @param TResource the resource being patched
+ * @param TPatchModel The input model for the PATCH request
+ * @param TBaseParameters Optional. Allows overriding the operation parameters
+ */
 @autoRoute
 @doc("Update a {name}", TResource)
 @armResourceUpdate(TResource)
@@ -152,13 +215,18 @@ op ArmCustomPatchSync<
   properties: TPatchModel
 ): ArmResponse<TResource> | ErrorResponse;
 
+/**
+ * Delete a resource Asynchronously
+ * @param TResource The resource being deleted
+ * @param TBaseParameters Optional. Allows overriding the parameters for the operation
+ */
 @autoRoute
 @doc("Delete a {name}", TResource)
 @extension("x-ms-long-running-operation", true)
 @extension(
   "x-ms-long-running-operation-options",
   {
-    `final-state-via`: "azure-async-operation",
+    `final-state-via`: "location",
   }
 )
 @armResourceDelete(TResource)
@@ -168,7 +236,7 @@ op ArmResourceDeleteAsync<
   TBaseParameters = BaseParameters<TResource>
 >(...ResourceInstanceParameters<TResource, TBaseParameters>):
   | ArmDeletedResponse
-  | ArmDeleteAcceptedResponse
+  | ArmDeleteAcceptedLroResponse
   | ArmDeletedNoContentResponse
   | ErrorResponse;
 
@@ -188,7 +256,7 @@ op ArmResourceDeleteSync<
 @extension(
   "x-ms-long-running-operation-options",
   {
-    `final-state-via`: "azure-async-operation",
+    `final-state-via`: "location",
   }
 )
 @armResourceAction(TResource)
@@ -204,7 +272,7 @@ op ArmResourceActionAsync<
   @doc("The content of the action request")
   @body
   body: TRequest
-): ArmResponse<TResponse> | ArmAcceptedResponse | ErrorResponse;
+): ArmAcceptedLroResponse | ArmResponse<TResponse> | ErrorResponse;
 
 @autoRoute
 @armResourceAction(TResource)
@@ -227,7 +295,7 @@ op ArmResourceActionSync<
 @extension(
   "x-ms-long-running-operation-options",
   {
-    `final-state-via`: "azure-async-operation",
+    `final-state-via`: "location",
   }
 )
 @armResourceAction(TResource)
@@ -242,7 +310,7 @@ op ArmResourceActionNoContentAsync<
   @doc("The content of the action request")
   @body
   body: TRequest
-): ArmNoContentResponse<"Action completed successfully."> | ArmAcceptedResponse | ErrorResponse;
+): ArmAcceptedLroResponse | ArmNoContentResponse<"Action completed successfully."> | ErrorResponse;
 
 @autoRoute
 @armResourceAction(TResource)

package/lib/responses.tsp

@@ -5,12 +5,18 @@ using Azure.ResourceManager.Foundations;
 
 namespace Azure.ResourceManager;
 
+/**
+ * The ARM synchronous OK response
+ */
 @doc("ARM operation completed successfully.")
 model ArmResponse<T> {
   ...OkResponse;
   ...Body<T>;
 }
 
+/**
+ * The ARM 201 response for a resource
+ */
 @doc("ARM create operation completed successfully.")
 model ArmCreatedResponse<T> {
   ...CreatedResponse;
@@ -18,11 +24,19 @@ model ArmCreatedResponse<T> {
   ...Body<T>;
 }
 
+/**
+ * The response for synchronous delete of a resource
+ */
 @doc("Resource deleted successfully.")
 model ArmDeletedResponse {
   ...OkResponse;
 }
 
+/**
+ * The response for asynchronous ARM delete ACCEPTED
+ */
+model ArmDeleteAcceptedLroResponse is ArmAcceptedLroResponse<"Resource deletion accepted.">;
+
 model ArmDeleteAcceptedResponse is ArmAcceptedResponse<"Resource deletion accepted.">;
 
 @doc(TMessage)
@@ -31,13 +45,32 @@ model ArmAcceptedResponse<TMessage extends string = "Resource operation accepted
   ...Azure.Core.Foundations.RetryAfterHeader;
 }
 
+/**
+ * The standard ARM response for asynchronous PATCH, POST, and DELETE operations
+ */
+model ArmAcceptedLroResponse<TMessage extends string = "Resource operation accepted.">
+  is ArmAcceptedResponse<TMessage> {
+  @doc("The Location header contains the URL where the status of the long running operation can be checked.")
+  @header("Location")
+  location?: string;
+}
+
+/**
+ * ARM response for a properly formed delete request, with no resource found
+ */
 model ArmDeletedNoContentResponse is ArmNoContentResponse<"Resource deleted successfully.">;
 
+/**
+ * Standard ARM NoContent (204) response
+ */
 @doc(TMessage)
 model ArmNoContentResponse<TMessage extends string = "Operation completed successfully."> {
   ...NoContentResponse;
 }
 
+/**
+ * The standard ARM error response
+ */
 @error
 @armCommonDefinition
 @doc("Common error response for all Azure Resource Manager APIs to return error details for failed operations.")

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@azure-tools/typespec-azure-resource-manager",
-  "version": "0.27.0",
+  "version": "0.28.0-dev.1",
   "author": "Microsoft Corporation",
   "description": "TypeSpec Azure Resource Manager library",
   "homepage": "https://azure.github.io/typespec-azure",
@@ -42,30 +42,30 @@
     "!dist/test/**"
   ],
   "peerDependencies": {
-    "@typespec/compiler": "~0.41.0",
-    "@azure-tools/typespec-azure-core": "~0.27.0",
-    "@azure-tools/typespec-autorest": "~0.27.0",
-    "@typespec/openapi": "~0.41.0",
-    "@typespec/rest": "~0.41.0",
-    "@typespec/http": "~0.41.0",
-    "@typespec/versioning": "~0.41.0"
+    "@typespec/compiler": ">=0.41.0",
+    "@azure-tools/typespec-azure-core": ">=0.27.0",
+    "@azure-tools/typespec-autorest": ">=0.27.0",
+    "@typespec/openapi": ">=0.41.0",
+    "@typespec/rest": ">=0.41.0",
+    "@typespec/http": ">=0.41.0",
+    "@typespec/versioning": ">=0.41.0"
   },
   "dependencies": {
-    "@typespec/lint": "~0.41.0"
+    "@typespec/lint": ">=0.41.0"
   },
   "devDependencies": {
-    "@typespec/compiler": "~0.41.0",
-    "@typespec/openapi": "~0.41.0",
-    "@azure-tools/typespec-azure-core": "~0.27.0",
-    "@azure-tools/typespec-autorest": "~0.27.0",
-    "@typespec/rest": "~0.41.0",
-    "@typespec/http": "~0.41.0",
-    "@typespec/versioning": "~0.41.0",
+    "@typespec/compiler": ">=0.41.0",
+    "@typespec/openapi": ">=0.41.0",
+    "@azure-tools/typespec-azure-core": ">=0.27.0",
+    "@azure-tools/typespec-autorest": ">=0.27.0",
+    "@typespec/rest": ">=0.41.0",
+    "@typespec/http": ">=0.41.0",
+    "@typespec/versioning": ">=0.41.0",
     "@types/mocha": "~10.0.0",
     "@types/node": "~18.11.9",
-    "@typespec/eslint-config-typespec": "~0.6.0",
-    "@typespec/library-linter": "~0.41.0",
-    "@typespec/eslint-plugin": "~0.41.0",
+    "@typespec/eslint-config-typespec": ">=0.6.0",
+    "@typespec/library-linter": ">=0.41.0",
+    "@typespec/eslint-plugin": ">=0.41.0",
     "eslint": "^8.12.0",
     "mocha": "~10.1.0",
     "c8": "~7.12.0",