@azure-tools/typespec-azure-resource-manager 0.30.0-dev.1 → 0.30.0-dev.10

package/lib/models.tsp

@@ -10,6 +10,7 @@ namespace Azure.ResourceManager;
  * Concrete tracked resource types can be created by aliasing this type using a specific property type.
  *
  * See more details on [different ARM resource type here.](https://azure.github.io/typespec-azure/docs/howtos/ARM/resource-type)
+ * @template TProperties A model containing the provider-specific properties for this resource
  */
 @doc("Concrete tracked resource types can be created by aliasing this type using a specific property type.")
 @armResourceInternal(TProperties)
@@ -25,6 +26,7 @@ model TrackedResource<TProperties> extends TrackedResourceBase {
  * Concrete proxy resource types can be created by aliasing this type using a specific property type.
  *
  * See more details on [different ARM resource type here.](https://azure.github.io/typespec-azure/docs/howtos/ARM/resource-type)
+ * @template TProperties A model containing the provider-specific properties for this resource
  */
 @doc("Concrete proxy resource types can be created by aliasing this type using a specific property type.")
 @armResourceInternal(TProperties)
@@ -40,6 +42,7 @@ model ProxyResource<TProperties> extends ProxyResourceBase {
  * Concrete extension resource types can be created by aliasing this type using a specific property type.
  *
  * See more details on [different ARM resource type here.](https://azure.github.io/typespec-azure/docs/howtos/ARM/resource-type)
+ * @template TProperties A model containing the provider-specific properties for this resource
  */
 @extensionResource
 @doc("Concrete extension resource types can be created by aliasing this type using a specific property type.")
@@ -54,12 +57,25 @@ model ExtensionResource<TProperties> extends ExtensionResourceBase {
 //#region
 
 //#region Standard extraction models
+
+/**
+ * Extracts the key (path) parameters from a resource and its parents
+ * @template TResource The resource to extract properties from
+ */
 @copyResourceKeyParameters
 model KeysOf<TResource> {}
 
+/**
+ * Extracts the key (path) parameters from the parent(s) of the given resource
+ * @template TResource The resource to extract properties from
+ */
 @copyResourceKeyParameters("parent")
 model ParentKeysOf<TResource> {}
 
+/**
+ * Model describing the provider namespace.
+ * @template TResource The resource provided by the namespace.
+ */
 model ProviderNamespace<TResource> {
   @path
   @segment("providers")
@@ -78,6 +94,7 @@ model ProviderNamespace<TResource> {
  *   otherArmId: ResourceIdentifier;
  *   networkId: ResourceIdentifier<[{type:"\\Microsoft.Network\\vnet"}]>
  *   vmIds: ResourceIdentifier<[{type:"\\Microsoft.Compute\\vm", scopes["*"]}]>
+ * @template T An array of allowed resource types for the resource reference
  */
 @doc("A type definition that refers the id to an ARM resource.")
 @format("arm-id")
@@ -157,12 +174,27 @@ model ManagedServiceIdentity {
   identity?: ManagedIdentityProperties;
 }
 
+/**
+ * Standard ARM definition of ManagedServiceIdentity for services
+ * that only support system-defined identities
+ */
 @doc("Managed identity for services that are constrained to system-assigned managed identities.")
 model ManagedSystemAssignedIdentity {
   @doc("The managed service identities assigned to this resource.")
   identity?: ManagedSystemIdentityProperties;
 }
 
+/**
+ * Model used only to spread in the standard `eTag` envelope property for a resource
+ * @example
+ *
+ * ```typespec
+ * model Foo is TrackedResource<FooProperties> {
+ *   // Only have standard Succeeded, Failed, Cancelled states
+ *   ...EntityTag;
+ * }
+ * ```
+ */
 @doc("The eTag property envelope.")
 model EntityTag {
   @doc("If eTag is provided in the response body, it may also be provided as a header per the normal etag convention.  Entity tags are used for comparing two or more entities from the same requested resource. HTTP/1.1 uses entity tags in the etag (section 14.19), If-Match (section 14.24), If-None-Match (section 14.26), and If-Range (section 14.27) header fields.")
@@ -170,6 +202,17 @@ model EntityTag {
   eTag?: string;
 }
 
+/**
+ * Model used only to spread in the standard `kind` envelope property for a resource
+ * @example
+ *
+ * ```typespec
+ * model Foo is TrackedResource<FooProperties> {
+ *   // Only have standard Succeeded, Failed, Cancelled states
+ *   ...ResourceKind;
+ * }
+ * ```
+ */
 @doc("The resource kind property envelope.")
 model ResourceKind {
   @doc("Metadata used by portal/tooling/etc to render different UX experiences for resources of the same type; e.g. ApiApps are a kind of Microsoft.Web/sites type.  If supported, the resource provider must validate and persist this value.")
@@ -178,22 +221,59 @@ model ResourceKind {
   kind?: string;
 }
 
+/**
+ * Paged response containing resources
+ * @template TResource The type of the values returned in the paged response (must be a resource)
+ */
 @doc("The response of a {name} list operation.", TResource)
 @friendlyName("{name}ListResult", TResource)
 model ResourceListResult<TResource extends ArmResource> is Azure.Core.Page<TResource>;
 
+/**
+ * Model used only to spread in the standard `plan` envelope property for a resource
+ * @example
+ *
+ * ```typespec
+ * model Foo is TrackedResource<FooProperties> {
+ *   // Only have standard Succeeded, Failed, Cancelled states
+ *   ...ResourcePlan;
+ * }
+ * ```
+ */
 @doc("The resource plan property envelope.")
 model ResourcePlan {
   @doc("Details of the resource plan.")
   plan?: ResourcePlanType;
 }
 
+/**
+ * Model used only to spread in the standard `sku` envelope property for a resource
+ * @example
+ *
+ * ```typespec
+ * model Foo is TrackedResource<FooProperties> {
+ *   // Only have standard Succeeded, Failed, Cancelled states
+ *   ...ResourceSku;
+ * }
+ * ```
+ */
 @doc("The SKU (Stock Keeping Unit) assigned to this resource.")
 model ResourceSku {
   @doc("The SKU (Stock Keeping Unit) assigned to this resource.")
   sku?: ResourceSkuType;
 }
 
+/**
+ * Model used only to spread in the standard `managedBy` envelope property for a resource
+ * @example
+ *
+ * ```typespec
+ * model Foo is TrackedResource<FooProperties> {
+ *   // Only have standard Succeeded, Failed, Cancelled states
+ *   ...ManagedBy;
+ * }
+ * ```
+ */
 @doc("The managedBy property envelope.")
 model ManagedBy {
   @doc("The fully qualified resource ID of the resource that manages this resource. Indicates if this resource is managed by another Azure resource. If this is present, complete mode deployment will not delete the resource if it is removed from the template since it is managed by another resource.")

package/lib/operations.tsp

@@ -10,7 +10,7 @@ namespace Azure.ResourceManager;
 
 /**
  * A resource list operation, at the subscription scope
- * @param TResource the resource being patched
+ * @template TResource the resource being patched
  */
 @autoRoute
 @doc("List {name} resources by subscription ID", TResource)
@@ -24,7 +24,10 @@ op ArmListBySubscription<TResource extends ArmResource>(
 
 /**
  * A resource list operation, at the scope of the resource's parent
- * @param TResource the resource being patched
+ * @template TResource the resource being patched
+ * @template TBaseParameters Optional. Allows overriding the operation parameters
+ * @template TParentName Optional. The name of the parent resource
+ * @template TParentFriendlyName Optional. The friendly name of the parent resource
  */
 @get
 @autoRoute
@@ -43,8 +46,8 @@ op ArmResourceListByParent<
 
 /**
  * A resource list operation, with scope determined by TBaseParameters
- * @param TResource the resource being patched
- * @param TBaseParameters Optional. Allows overriding the operation parameters
+ * @template TResource the resource being patched
+ * @template TBaseParameters Optional. Allows overriding the operation parameters
  */
 @get
 @autoRoute
@@ -61,8 +64,8 @@ op ArmResourceListAtScope<
 
 /**
  * A resource GET operation
- * @param TResource the resource being patched
- * @param TBaseParameters Optional. Allows overriding the operation parameters
+ * @template TResource the resource being patched
+ * @template TBaseParameters Optional. Allows overriding the operation parameters
  */
 @autoRoute
 @doc("Get a {name}", TResource)
@@ -74,8 +77,8 @@ op ArmResourceRead<TResource extends ArmResource, TBaseParameters = BaseParamete
 
 /**
  * A long-running resource CreateOrUpdate (PUT)
- * @param TResource the resource being patched
- * @param TBaseParameters Optional. Allows overriding the operation parameters
+ * @template TResource the resource being patched
+ * @template TBaseParameters Optional. Allows overriding the operation parameters
  */
 @autoRoute
 @doc("Create a {name}", TResource)
@@ -101,8 +104,8 @@ op ArmResourceCreateOrUpdateAsync<
 
 /**
  * A resource CreateOrUpdate (PUT)
- * @param TResource the resource being patched
- * @param TBaseParameters Optional. Allows overriding the operation parameters
+ * @template TResource the resource being patched
+ * @template TBaseParameters Optional. Allows overriding the operation parameters
  */
 @autoRoute
 @doc("Create a {name}", TResource)
@@ -121,8 +124,8 @@ op ArmResourceCreateOrUpdateSync<
 
 /**
  * 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
+ * @template TResource the resource being patched
+ * @template TBaseParameters Optional. Allows overriding the operation parameters
  */
 alias ArmTagsPatchAsync<
   TResource extends ArmResource,
@@ -132,9 +135,9 @@ alias ArmTagsPatchAsync<
 
 /**
  * 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
+ * @template TResource the resource being patched
+ * @template TProperties The model type of the resource properties
+ * @template TBaseParameters Optional. Allows overriding the operation parameters
  */
 alias ArmResourcePatchAsync<
   TResource extends ArmResource,
@@ -144,9 +147,9 @@ alias ArmResourcePatchAsync<
 
 /**
  * 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
+ * @template TResource the resource being patched
+ * @template TPatchModel The input model for the PATCH request
+ * @template TBaseParameters Optional. Allows overriding the operation parameters
  */
 @autoRoute
 @doc("Update a {name}", TResource)
@@ -173,8 +176,8 @@ op ArmCustomPatchAsync<
 
 /**
  * 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
+ * @template TResource the resource being patched
+ * @template TBaseParameters Optional. Allows overriding the operation parameters
  */
 alias ArmTagsPatchSync<
   TResource extends ArmResource,
@@ -183,9 +186,9 @@ alias ArmTagsPatchSync<
 
 /**
  * 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
+ * @template TResource the resource being patched
+ * @template TProperties The model type of the resource properties
+ * @template TBaseParameters Optional. Allows overriding the operation parameters
  */
 alias ArmResourcePatchSync<
   TResource extends ArmResource,
@@ -195,9 +198,9 @@ alias ArmResourcePatchSync<
 
 /**
  * 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
+ * @template TResource the resource being patched
+ * @template TPatchModel The input model for the PATCH request
+ * @template TBaseParameters Optional. Allows overriding the operation parameters
  */
 @autoRoute
 @doc("Update a {name}", TResource)
@@ -217,8 +220,8 @@ op ArmCustomPatchSync<
 
 /**
  * Delete a resource Asynchronously
- * @param TResource The resource being deleted
- * @param TBaseParameters Optional. Allows overriding the parameters for the operation
+ * @template TResource The resource being deleted
+ * @template TBaseParameters Optional. Allows overriding the parameters for the operation
  */
 @autoRoute
 @doc("Delete a {name}", TResource)
@@ -240,6 +243,11 @@ op ArmResourceDeleteAsync<
   | ArmDeletedNoContentResponse
   | ErrorResponse;
 
+/**
+ * Delete a resource synchronously
+ * @template TResource The resource being deleted
+ * @template TBaseParameters Optional. Allows overriding the parameters for the operation
+ */
 @autoRoute
 @doc("Delete a {name}", TResource)
 @armResourceDelete(TResource)
@@ -251,6 +259,13 @@ op ArmResourceDeleteSync<
   ...ResourceInstanceParameters<TResource, TBaseParameters>
 ): ArmDeletedResponse | ArmDeletedNoContentResponse | ErrorResponse;
 
+/**
+ * A long-running resource action.
+ * @template TResource The resource being acted upon
+ * @template TRequest The request model for the action
+ * @template TResponse The response model for the action
+ * @template TBaseParameters Optional. Allows overriding the parameters for the operation
+ */
 @autoRoute
 @extension("x-ms-long-running-operation", true)
 @extension(
@@ -274,6 +289,13 @@ op ArmResourceActionAsync<
   body: TRequest
 ): ArmAcceptedLroResponse | ArmResponse<TResponse> | ErrorResponse;
 
+/**
+ * A synchronous resource action.
+ * @template TResource The resource being acted upon
+ * @template TRequest The request model for the action
+ * @template TResponse The response model for the action
+ * @template TBaseParameters Optional. Allows overriding the parameters for the operation
+ */
 @autoRoute
 @armResourceAction(TResource)
 @post
@@ -290,6 +312,12 @@ op ArmResourceActionSync<
   body: TRequest
 ): ArmResponse<TResponse> | ErrorResponse;
 
+/**
+ * A long-running resource action that returns no content.
+ * @template TResource The resource being acted upon
+ * @template TRequest The request model for the action
+ * @template TBaseParameters Optional. Allows overriding the parameters for the operation
+ */
 @autoRoute
 @extension("x-ms-long-running-operation", true)
 @extension(
@@ -312,6 +340,12 @@ op ArmResourceActionNoContentAsync<
   body: TRequest
 ): ArmAcceptedLroResponse | ArmNoContentResponse<"Action completed successfully."> | ErrorResponse;
 
+/**
+ * A synchronous resource action that returns no content.
+ * @template TResource The resource being acted upon
+ * @template TRequest The request model for the action
+ * @template TBaseParameters Optional. Allows overriding the parameters for the operation
+ */
 @autoRoute
 @armResourceAction(TResource)
 @post
@@ -326,3 +360,36 @@ op ArmResourceActionNoContentSync<
   @body
   body: TRequest
 ): ArmNoContentResponse<"Action completed successfully."> | ErrorResponse;
+
+/**
+ * Adds check global name availability operation, normally used if
+ * a resource name must be globally unique (for example, if the resource
+ * exposes and endpoint that uses the resource name in the url)
+ * @template TRequest the availability request, defaults to the standard request, contsining name and tesource type
+ * @template TResponse the availability response, default to the standard response
+ * @template TAdditionalParams A model specifying additiional non-path parameters to the availability request
+ */
+alias checkGlobalNameAvailability<
+  TRequest extends object = Azure.ResourceManager.Foundations.CheckNameAvailabilityRequest,
+  TResponse extends object = CheckNameAvailabilityResponse,
+  TAdditionalParams extends object = {}
+> = checkNameAvailability<SubscriptionIdParameter, TRequest, TResponse, TAdditionalParams>;
+
+/**
+ * Adds check location-specific name availability operation, normally used if
+ * a resource name must be globally unique (for example, if the resource
+ * exposes and endpoint that uses the resource name in the url)
+ * @template TRequest the availability request, defaults to the standard request, contsining name and tesource type
+ * @template TResponse the availability response, default to the standard response
+ * @template TAdditionalParams A model specifying additiional non-path parameters to the availability request
+ */
+alias checkLocalNameAvailability<
+  TRequest extends object = Azure.ResourceManager.Foundations.CheckNameAvailabilityRequest,
+  TResponse extends object = CheckNameAvailabilityResponse,
+  TAdditionalParams extends object = {}
+> = checkNameAvailability<
+  SubscriptionIdParameter & LocationParameter,
+  TRequest,
+  TResponse,
+  TAdditionalParams
+>;

package/lib/parameters.tsp

@@ -86,6 +86,8 @@ model ResourceUriParameter {
 /**
  * The dynamic parameters of a resource instance - pass in the proper base type to indicate
  * where the resource is based.  The default is in a resource group
+ * @template TResource The resource to get parameters for
+ * @template TBaseParameters The parameters representing the base Uri of the resource
  */
 model ResourceInstanceParameters<
   TResource extends ArmResource,
@@ -99,6 +101,8 @@ model ResourceInstanceParameters<
 /**
  * The dynamic parameters of a list call for a resource instance - pass in the proper base type to indicate
  * where the list should take place.  The default is in a resource group
+ * @template TResource The resource to get parameters for
+ * @template TBaseParameters The parameters representing the base Uri of the resource
  */
 model ResourceParentParameters<
   TResource extends ArmResource,
@@ -111,6 +115,7 @@ model ResourceParentParameters<
 
 /**
  * The dynamic parameters of a list call for an extension resource instance.
+ * @template TResource The extension resource
  */
 alias ExtensionResourceInstanceParameters<TResource extends ArmResource> = ResourceInstanceParameters<
   TResource,
@@ -119,6 +124,7 @@ alias ExtensionResourceInstanceParameters<TResource extends ArmResource> = Resou
 
 /**
  * The dynamic parameters of a list call for a tenant resource instance.
+ * @template TResource the tenant resource
  */
 alias TenantInstanceParameters<TResource extends ArmResource> = ResourceInstanceParameters<
   TResource,

package/lib/responses.tsp

@@ -7,6 +7,7 @@ namespace Azure.ResourceManager;
 
 /**
  * The ARM synchronous OK response
+ * @template T The contents of the response body
  */
 @doc("ARM operation completed successfully.")
 model ArmResponse<T> {
@@ -16,6 +17,7 @@ model ArmResponse<T> {
 
 /**
  * The ARM 201 response for a resource
+ * @template T The contents of the response body
  */
 @doc("ARM create operation completed successfully.")
 model ArmCreatedResponse<T> {
@@ -37,8 +39,15 @@ model ArmDeletedResponse {
  */
 model ArmDeleteAcceptedLroResponse is ArmAcceptedLroResponse<"Resource deletion accepted.">;
 
+/**
+ * The response for synchronous ARM delete ACCEPTED
+ */
 model ArmDeleteAcceptedResponse is ArmAcceptedResponse<"Resource deletion accepted.">;
 
+/**
+ * The standard ACCEPTED response
+ * @template TMessage The description of the response status (defaults to `Resource operation accepted`)
+ */
 @doc(TMessage)
 model ArmAcceptedResponse<TMessage extends string = "Resource operation accepted."> {
   ...AcceptedResponse;
@@ -47,6 +56,7 @@ model ArmAcceptedResponse<TMessage extends string = "Resource operation accepted
 
 /**
  * The standard ARM response for asynchronous PATCH, POST, and DELETE operations
+ * @template TMessage The description of the response status (defaults to `Resource operation accepted`)
  */
 model ArmAcceptedLroResponse<TMessage extends string = "Resource operation accepted.">
   is ArmAcceptedResponse<TMessage> {
@@ -62,6 +72,7 @@ model ArmDeletedNoContentResponse is ArmNoContentResponse<"Resource deleted succ
 
 /**
  * Standard ARM NoContent (204) response
+ * @template TMessage The description of the response status (defaults to `Operation completed successfully`)
  */
 @doc(TMessage)
 model ArmNoContentResponse<TMessage extends string = "Operation completed successfully."> {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@azure-tools/typespec-azure-resource-manager",
-  "version": "0.30.0-dev.1",
+  "version": "0.30.0-dev.10",
   "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.43.0",
-    "@azure-tools/typespec-azure-core": ">=0.29.0",
-    "@azure-tools/typespec-autorest": ">=0.29.0",
-    "@typespec/openapi": ">=0.43.0",
-    "@typespec/rest": ">=0.43.0",
-    "@typespec/http": ">=0.43.0",
-    "@typespec/versioning": ">=0.43.0"
+    "@typespec/compiler": "~0.43.0 || >=0.44.0-dev <0.44.0",
+    "@azure-tools/typespec-azure-core": "~0.29.0 || >=0.30.0-dev <0.30.0",
+    "@azure-tools/typespec-autorest": "~0.29.0 || >=0.30.0-dev <0.30.0",
+    "@typespec/openapi": "~0.43.0 || >=0.44.0-dev <0.44.0",
+    "@typespec/rest": "~0.43.0 || >=0.44.0-dev <0.44.0",
+    "@typespec/http": "~0.43.1 || >=0.44.0-dev <0.44.0",
+    "@typespec/versioning": "~0.43.0 || >=0.44.0-dev <0.44.0"
   },
   "dependencies": {
-    "@typespec/lint": ">=0.43.0"
+    "@typespec/lint": "~0.43.0 || >=0.44.0-dev <0.44.0"
   },
   "devDependencies": {
-    "@typespec/compiler": ">=0.43.0",
-    "@typespec/openapi": ">=0.43.0",
-    "@azure-tools/typespec-azure-core": ">=0.29.0",
-    "@azure-tools/typespec-autorest": ">=0.29.0",
-    "@typespec/rest": ">=0.43.0",
-    "@typespec/http": ">=0.43.0",
-    "@typespec/versioning": ">=0.43.0",
+    "@typespec/compiler": "~0.43.0 || >=0.44.0-dev <0.44.0",
+    "@typespec/openapi": "~0.43.0 || >=0.44.0-dev <0.44.0",
+    "@azure-tools/typespec-azure-core": "~0.29.0 || >=0.30.0-dev <0.30.0",
+    "@azure-tools/typespec-autorest": "~0.29.0 || >=0.30.0-dev <0.30.0",
+    "@typespec/rest": "~0.43.0 || >=0.44.0-dev <0.44.0",
+    "@typespec/http": "~0.43.1 || >=0.44.0-dev <0.44.0",
+    "@typespec/versioning": "~0.43.0 || >=0.44.0-dev <0.44.0",
     "@types/mocha": "~10.0.0",
     "@types/node": "~18.11.9",
-    "@typespec/eslint-config-typespec": ">=0.6.0",
-    "@typespec/library-linter": ">=0.43.0",
-    "@typespec/eslint-plugin": ">=0.43.0",
+    "@typespec/eslint-config-typespec": "~0.6.0 || >=0.7.0-dev <0.7.0",
+    "@typespec/library-linter": "~0.43.0 || >=0.44.0-dev <0.44.0",
+    "@typespec/eslint-plugin": "~0.43.0 || >=0.44.0-dev <0.44.0",
     "eslint": "^8.36.0",
     "mocha": "~10.2.0",
     "mocha-junit-reporter": "~2.2.0",