@azure-tools/typespec-azure-resource-manager 0.31.0-dev.1 → 0.31.0-dev.3

package/README.md

@@ -2,17 +2,6 @@
 
 This is a library that provides model types and interfaces which can be used to define an Azure Resource Manager service API.
 
-## Table of Contents
-
-- [Getting Started](#getting-started)
-  - [Creating a project with `tsp init`](#creating-a-project-with-typespec-init)
-  - [Creating a project manually](#creating-a-project-manually)
-- [Concepts](#concepts)
-  - [Defining the Service](#defining-the-service)
-  - [Defining Resource Types](#defining-resource-types)
-- [Generating an OpenAPI Specification](#generating-an-openapi-specification)
-- [A Complete Example](#a-complete-example)
-
 ## Getting Started
 
 To author an Azure Resource Manager service definition, you will first need to create a TypeSpec project for your service.
@@ -24,323 +13,12 @@ https://github.com/Azure/typespec-azure/blob/main/packages/typespec-providerhub-
 
 Before using this library, you should familiarize yourself with the TypeSpec language and tools. You can do this by reading the [TypeSpec tutorial](https://github.com/microsoft/typespec/blob/main/docs/tutorial.md).
 
-### Defining the Service
-
-To define an Azure Resource Manager service, the first thing you will need to do is define the service namespace and decorate it with the `serviceTitle`, `serviceVersion` and `armProviderNamespace` decorators:
-
-```typespec
-@armProviderNamespace
-@service({title: "<service name>", version: "<service version>"})
-namespace <mynamespace>;
-```
-
-For example:
-
-```typespec
-@armProviderNamespace
-@service({
-  title: "Contoso User Service",
-  version: "2020-10-01-preview",
-})
-namespace Contoso.Users;
-```
-
-### The `using` keyword
-
-Just after the `namespace` declaration, you will also need to include a few `using` statements to pull in symbols from the namespaces of libraries you will for your specification.
-
-For example, these lines pull in symbols from the `@typespec/rest` and `@azure-tools/typespec-azure-resource-manager`:
-
-```
-using TypeSpec.Http;
-using TypeSpec.Rest;
-using Azure.ResourceManager;
-```
-
-### Defining Resource Types
-
-A resource provider is composed of resources. The TypeSpec Azure Resource Manager library makes it much easier to define the structure and endpoints of such resources.
-
-There are three essential components of a resource defined with TypeSpec:
-
-- A model type representing the resource, derived from one of the [base resource types](#base-resource-types)
-- A model type defining the properties of the resource type
-- An interface that defines the operations that can be performed on the resource type, usually a combination of [standard resource operations](#standard-resource-operations) and [custom actions](#custom-actions)
-
-Read the [TypeSpec tutorial](https://github.com/Microsoft/typespec/blob/main/docs/tutorial.md) to learn the basics about TypeSpec model types and interfaces.
-
-#### 1. **Define a model representing the `properties` of the ARM resource**
-
-Each resource type must have a properties type which defines its custom properties. This type will be exposed as the `properties` property of the resource type.
-
-```typespec
-@doc("The properties of UserResource")
-model UserResourceProperties {
-  @doc("The user's full name")
-  fullName: string;
-
-  @doc("The user's email address.")
-  emailAddress: string;
-}
-```
-
-#### 2. **Define a model representing the resource type**
-
-Resource types are defined as plain models which pull in a standard resource type using the `is` keyword.
-
-You define a resource type, you need the following:
-
-- A `name` property which is marked with the following decorators
-  - `@key`: Specifies the parameter name for this resource type in the service URI hierarchy
-  - `@segment`: Specifies the name of the resource "collection", the URI segment that comes just before the parameter name which identifies the resource type
-- A second model type which defines the resource type's custom properties as we described in step 1
-
-Here we define a tracked resource called `UserResource`:
-
-```typespec
-@doc("A UserResource")
-model UserResource is TrackedResource<UserResourceProperties> {
-  @key("userName")
-  @segment("users")
-  name: string;
-}
-```
-
-#### 3. **Define an interface with operations for the resource type**
-
-```typespec
-@armResourceOperations
-interface Users extends TrackedResourceOperations<UserResource> {}
-```
-
-This will now produce all the endpoints(`get`, `post`, `put`, `patch` and `delete`, listByResourceGroup, listBySubscription) for a resource called `UserResources` and the `operations` endpoint for the service:
-
-| Method & Path                                                                                                        | Description                             |
-| -------------------------------------------------------------------------------------------------------------------- | --------------------------------------- |
-| `GET /providers/Contoso.Users/operations`                                                                            | List all operations for your service    |
-| `GET /subscriptions/{subscriptionId}/providers/Contoso.Users/users`                                                  | list all UserResource by subscription   |
-| `GET /subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Contoso.Users/users`               | list all UserResource by resource group |
-| `GET /subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Contoso.Users/users/{userName}`    | get item                                |
-| `PUT /subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Contoso.Users/users/{userName}`    | insert item                             |
-| `PATCH /subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Contoso.Users/users/{userName}`  | patch item                              |
-| `DELETE /subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Contoso.Users/users/{userName}` | delete item                             |
-
-#### Base Resource Types
-
-Here are the base resource types you can use when defining your own ARM resources:
-
-| Name                           | Description                                                                            |
-| ------------------------------ | -------------------------------------------------------------------------------------- |
-| TrackedResource<TProperties>   | Defines a normal ARM resource where `TProperties` is the model of the `properties`     |
-| ProxyResource<TProperties>     | Defines a proxy ARM resource where `TProperties` is the model of the `properties`      |
-| ExtensionResource<TProperties> | Defines an extension ARM resource where `TProperties` is the model of the `properties` |
-
-### Defining Child Resource Types
-
-You can create parent/child relationships between resource types by using the `@parentResource` decorator when defining a resource type.
-
-For example, here's how you could create a new `AddressResource` resource under the `UserResource` defined above:
-
-```typespec
-@doc("An address resource belonging to a user resource.")
-@parentResource(UserResource)
-model AddressResource is ProxyResource<AddressResourceProperties> {
-  @key("addressName")
-  @segment("addresses")
-  name: string;
-}
-
-@doc("The properties of AddressResource")
-model AddressResourceProperties {
-  @doc("The street address.")
-  streetAddress: string;
-
-  @doc("The city of the address.")
-  city: string;
-
-  @doc("The state of the address.")
-  state: string;
-
-  @doc("The zip code of the address.")
-  zip: int32;
-}
-
-@armResourceOperations
-interface Addresses extends ProxyResourceOperations<AddressResource> {}
-```
-
-### Defining Custom Actions
-
-Some resources will provide more than the standard CRUD operations and will need to define a custom action endpoint. Additional resource operations can be added to the `interface` where you pulled in standard resource operations.
-
-For example, to add an additional `POST` action called `/notify` to the standard operations of `UserResource`:
-
-```typespec
-@doc("The details of a user notification.")
-model NotificationDetails {
-  @doc("The notification message.")
-  message: string;
-
-  @doc("If true, the notification is urgent.")
-  urgent: boolean;
-}
-
-@armResourceOperations
-interface Users extends TrackedResourceOperations<UserResource, UserResourceProperties> {
-  @post
-  @doc("Send a notification to the user")
-  @segment("notify")
-  NotifyUser(
-    ...ResourceInstanceParameters<UserResource>,
-    @body notification: NotificationDetails
-  ): ArmResponse<string> | ErrorResponse;
-}
-```
-
-#### ARM Response Types
-
-Custom operations in ARM still need to respect the correct response schema. This library provides standard ARM response types to help with reusability and compliance.
-
-| Model                         | Code | Description                                   |
-| ----------------------------- | ---- | --------------------------------------------- |
-| `ArmResponse<T>`              | 200  | Base Arm 200 response.                        |
-| `ArmCreatedResponse<T>`       | 201  | Resource created response                     |
-| `ArmDeletedResponse`          | 200  | Resource deleted response                     |
-| `ArmDeleteAcceptedResponse`   | 202  | Resource deletion in progress response        |
-| `ArmDeletedNoContentResponse` | 204  | Resource deleted response                     |
-| `Page<T>`                     | 200  | Return a list of resource with ARM pagination |
-| `ErrorResponse<T>`            | x    | Error response                                |
-
-#### Common Operation Parameters
-
-There are a number of model types which specify common parameters which are used in resource type operations:
-
-| Model                        | In           | Description                                                        |
-| ---------------------------- | ------------ | ------------------------------------------------------------------ |
-| `ApiVersionParameter`        | query        | `api-version` parameter                                            |
-| `SubscriptionIdParameter`    | path         | Subscription ID path parameter                                     |
-| `ResourceGroupNameParameter` | path         | Resource Group Name path parameter                                 |
-| `CommonResourceParameters`   | path & query | Group of Api version, Subscription ID and Resource group parameter |
-| `ResourceUriParameter`       | path         | Resource uri path parameter                                        |
-| `OperationIdParameter`       | path         | Operation Id path parameter                                        |
-
-## Generating an OpenAPI Specification
-
-To generate an OpenAPI v2 (Swagger) specification from the service definition, run the following command inside of the project folder:
-
-```
-tsp compile . --emit @azure-tools/typespec-autorest
-```
-
-This will create a file in the `tsp-output` subfolder called `openapi.json`.
-
-## A Complete Example
-
-Here's a complete example `main.tsp` file based on all of the snippets in this README:
-
-```typespec
-import "@typespec/http";
-import "@typespec/rest";
-import "@typespec/versioning";
-import "@azure-tools/typespec-providerhub";
-import "@azure-tools/typespec-azure-core";
-import "@azure-tools/typespec-azure-resource-manager";
-
-using TypeSpec.Http;
-using TypeSpec.Rest;
-using TypeSpec.Versioning;
-using Azure.Core;
-using Azure.ResourceManager;
-
-@armProviderNamespace
-@service({
-  title: "ContosoProviderHubClient",
-  version: "2021-01-01-preview",
-})
-@doc("Contoso Resource Provider management API.")
-@useDependency(Azure.ResourceManager.Versions.v1_0_Preview_1)
-namespace Microsoft.ContosoProviderHub;
-
-interface Operations extends Azure.ResourceManager.Operations {}
-
-@lroStatus
-enum ProvisioningState {
-  ...ResourceProvisioningState,
-  Provisioning,
-  Updating,
-  Deleting,
-  Accepted,
-}
-
-@doc("The properties of UserResource")
-model UserResourceProperties {
-  @doc("The user's full name")
-  fullName: string;
-
-  @doc("The user's email address.")
-  emailAddress: string;
-
-  @doc("The status of the last operation.")
-  provisioningState?: ProvisioningState;
-}
-
-@doc("A UserResource")
-model UserResource is TrackedResource<UserResourceProperties> {
-  @key("userName")
-  @segment("users")
-  @doc("Address name")
-  @path
-  name: string;
-}
-
-@doc("The details of a user notification.")
-model NotificationDetails {
-  @doc("The notification message.")
-  message: string;
-
-  @doc("If true, the notification is urgent.")
-  urgent: boolean;
-}
-
-@armResourceOperations
-interface Users extends TrackedResourceOperations<UserResource, UserResourceProperties> {
-  @post
-  @doc("Send a notification to the user")
-  @segment("notify")
-  notifyUser(
-    ...ResourceInstanceParameters<UserResource>,
-    @body notification: NotificationDetails
-  ): ArmResponse<string> | ErrorResponse;
-}
-
-@doc("An address resource belonging to a user resource.")
-@parentResource(UserResource)
-model AddressResource is ProxyResource<AddressResourceProperties> {
-  @doc("Address name")
-  @key("addressName")
-  @segment("addresses")
-  @path
-  name: string;
-}
-
-@doc("The properties of AddressResource")
-model AddressResourceProperties {
-  @doc("The street address.")
-  streetAddress: string;
-
-  @doc("The city of the address.")
-  city: string;
+## Documentation
 
-  @doc("The state of the address.")
-  state: string;
+All relevant documentation for using the TypeSpec ARM library can be found [here](https://azure.github.io/typespec-azure/).
 
-  @doc("The zip code of the address.")
-  zip: int32;
+[Getting Started Tutorial](https://azure.github.io/typespec-azure/docs/getstarted/azure-resource-manager/step00)
 
-  @doc("The status of the last operation.")
-  provisioningState?: ProvisioningState;
-}
+[How-tos and Examples](https://azure.github.io/typespec-azure/docs/howtos/ARM/arm-rules)
 
-@armResourceOperations
-interface Addresses extends ProxyResourceOperations<AddressResource> {}
-```
+[Reference](https://azure.github.io/typespec-azure/docs/libraries/azure-resource-manager/reference)

package/lib/arm.foundations.tsp

@@ -64,10 +64,19 @@ model ExtensionResourceBase extends ArmResource {}
  * An internal enum to indicate the resource support for various path types
  */
 enum ResourceHome {
+  @doc("The resource is bound to a tenant")
   Tenant,
+
+  @doc("The resource is bound to a subscription")
   Subscription,
+
+  @doc("The resource is bound to a location")
   Location,
+
+  @doc("The resource is bound to a resource group")
   ResourceGroup,
+
+  @doc("The resource is bound to an extension")
   Extension,
 }
 
@@ -78,8 +87,13 @@ enum ResourceHome {
 The intended executor of the operation; as in Resource Based Access Control (RBAC) and audit logs UX. Default value is "user,system"
 """)
 enum Origin {
+  @doc("Indicates the operation is initiated by a user.")
   user,
+
+  @doc("Indicates the operation is initiated by a system.")
   system,
+
+  @doc("Indicates the operation is initiated by a user or system.")
   `user,system`,
 }
 
@@ -90,6 +104,7 @@ enum Origin {
 Enum. Indicates the action type. "Internal" refers to actions that are for internal only APIs.
 """)
 enum ActionType {
+  @doc("Actions are for internal-only APIs.")
   Internal,
 }
 
@@ -264,9 +279,16 @@ model ArmTagsProperty {
 // NOTE: This is how the enum is named in types.json
 @doc("The kind of entity that created the resource.")
 enum createdByType {
+  @doc("The entity was created by a user.")
   User,
+
+  @doc("The entity was created by an application.")
   Application,
+
+  @doc("The entity was created by a managed identity.")
   ManagedIdentity,
+
+  @doc("The entity was created by a key.")
   Key,
 }
 
@@ -357,9 +379,16 @@ model UserAssignedIdentity {
  */
 @doc("The kind of managed identity assigned to this resource.")
 enum ManagedIdentityType {
+  @doc("No managed identity.")
   None,
+
+  @doc("System assigned managed identity.")
   SystemAssigned,
+
+  @doc("User assigned managed identity.")
   UserAssigned,
+
+  @doc("System and user assigned managed identity.")
   SystemAndUserAssigned: "SystemAssigned, UserAssigned",
 }
 
@@ -368,7 +397,10 @@ enum ManagedIdentityType {
  */
 @doc("The kind of managemed identity assigned to this resource.")
 enum ManagedSystemIdentityType {
+  @doc("No managed system identity.")
   None,
+
+  @doc("System assigned managed system identity.")
   SystemAssigned,
 }
 
@@ -495,9 +527,16 @@ model ResourceSkuType {
  */
 @doc("Available service tiers for the SKU.")
 enum SkuTier {
+  @doc("The Free service tier.")
   Free,
+
+  @doc("The Basic service tier.")
   Basic,
+
+  @doc("The Standard service tier.")
   Standard,
+
+  @doc("The Premium service tier.")
   Premium,
 }
 
@@ -576,7 +615,10 @@ model CheckNameAvailabilityRequest {
  */
 @doc("Possible reasons for a name not being available.")
 enum CheckNameAvailabilityReason {
+  @doc("Name is invalid.")
   Invalid,
+
+  @doc("Name already exists.")
   AlreadyExists,
 }
 

package/lib/arm.tsp

@@ -28,7 +28,9 @@ namespace Azure.ResourceManager;
 /**
  * Supported versions of Azure.ResourceManager building blocks.
  */
+@doc("Supported versions of Azure.ResourceManager building blocks.")
 enum Versions {
+  @doc("Version 1.0-preview.1")
   @useDependency(Azure.Core.Versions.v1_0_Preview_1)
   v1_0_Preview_1: "1.0-preview.1",
 }

package/lib/models.tsp

@@ -141,8 +141,13 @@ model ResourceIdentifierAllowedResource {
 @doc("The provisioning state of a resource type.")
 @Azure.Core.lroStatus
 enum ResourceProvisioningState {
+  @doc("Resource has been created.")
   Succeeded,
+
+  @doc("Resource creation failed.")
   Failed,
+
+  @doc("Resource creation was canceled.")
   Canceled,
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@azure-tools/typespec-azure-resource-manager",
-  "version": "0.31.0-dev.1",
+  "version": "0.31.0-dev.3",
   "author": "Microsoft Corporation",
   "description": "TypeSpec Azure Resource Manager library",
   "homepage": "https://azure.github.io/typespec-azure",
@@ -44,7 +44,7 @@
   "peerDependencies": {
     "@typespec/compiler": "~0.44.0 || >=0.45.0-dev <0.45.0",
     "@azure-tools/typespec-azure-core": "~0.30.1 || >=0.31.0-dev <0.31.0",
-    "@azure-tools/typespec-autorest": "~0.30.0 || >=0.31.0-dev <0.31.0",
+    "@azure-tools/typespec-autorest": "~0.30.1 || >=0.31.0-dev <0.31.0",
     "@typespec/openapi": "~0.44.0 || >=0.45.0-dev <0.45.0",
     "@typespec/rest": "~0.44.0 || >=0.45.0-dev <0.45.0",
     "@typespec/http": "~0.44.0 || >=0.45.0-dev <0.45.0",
@@ -57,7 +57,7 @@
     "@typespec/compiler": "~0.44.0 || >=0.45.0-dev <0.45.0",
     "@typespec/openapi": "~0.44.0 || >=0.45.0-dev <0.45.0",
     "@azure-tools/typespec-azure-core": "~0.30.1 || >=0.31.0-dev <0.31.0",
-    "@azure-tools/typespec-autorest": "~0.30.0 || >=0.31.0-dev <0.31.0",
+    "@azure-tools/typespec-autorest": "~0.30.1 || >=0.31.0-dev <0.31.0",
     "@typespec/rest": "~0.44.0 || >=0.45.0-dev <0.45.0",
     "@typespec/http": "~0.44.0 || >=0.45.0-dev <0.45.0",
     "@typespec/versioning": "~0.44.0 || >=0.45.0-dev <0.45.0",