From c0fa9da31380514a1240300372dc955020a8d0c4 Mon Sep 17 00:00:00 2001 From: Tim Lovell-Smith Date: Mon, 26 Oct 2020 23:36:51 -0700 Subject: [PATCH] Update common types with Operation + OperationListResult (#11356) * Add titles and descriptions for 'commontypes/v1/Resource' common types. * Define the 'Operation' and 'OperationListResult' common types in common-types v1. * REFATOR: Update 'redis.json' to use common-types v1 OperationListResult. * Revert "REFATOR: Update 'redis.json' to use common-types v1 OperationListResult." which the linter breaking change the detection wasn't a fan of. This reverts commit f8f696fa405d0b26e40939715bfb1f2b1804a91b. * Improvements to descriptions, and 'readOnly' annotations on OperationListResult * Fix typo in the Resource description. * Also add the Operation definition to common-types' v2/types.json, along with most of the improvements to descriptions etc. * Revise descriptions with API consumers as intended audience. --- .../resource-management/v1/types.json | 112 ++++++++++++++++-- .../resource-management/v2/types.json | 107 +++++++++++++++-- 2 files changed, 198 insertions(+), 21 deletions(-) diff --git a/specification/common-types/resource-management/v1/types.json b/specification/common-types/resource-management/v1/types.json index 7415ea29529d..765dd32c358d 100644 --- a/specification/common-types/resource-management/v1/types.json +++ b/specification/common-types/resource-management/v1/types.json @@ -7,11 +7,13 @@ "paths": {}, "definitions": { "Resource": { + "title": "Resource", + "description": "Common fields that are returned in the response for all Azure Resource Manager resources", "properties": { "id": { "readOnly": true, "type": "string", - "description": "Fully qualified resource Id for the resource. Ex - /subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/{resourceProviderNamespace}/{resourceType}/{resourceName}" + "description": "Fully qualified resource ID for the resource. Ex - /subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/{resourceProviderNamespace}/{resourceType}/{resourceName}" }, "name": { "readOnly": true, @@ -21,14 +23,15 @@ "type": { "readOnly": true, "type": "string", - "description": "The type of the resource. Ex- Microsoft.Compute/virtualMachines or Microsoft.Storage/storageAccounts." + "description": "The type of the resource. E.g. \"Microsoft.Compute/virtualMachines\" or \"Microsoft.Storage/storageAccounts\"" } }, "x-ms-azure-resource": true }, "AzureEntityResource": { "x-ms-client-name": "AzureEntityResource", - "description": "The resource model definition for a Azure Resource Manager resource with an etag.", + "title": "Entity Resource", + "description": "The resource model definition for an Azure Resource Manager resource with an etag.", "properties": { "etag": { "type": "string", @@ -43,7 +46,8 @@ ] }, "TrackedResource": { - "description": "The resource model definition for a ARM tracked top level resource", + "title": "Tracked Resource", + "description": "The resource model definition for an Azure Resource Manager tracked top level resource which has 'tags' and a 'location'", "properties": { "tags": { "type": "object", @@ -76,7 +80,8 @@ ] }, "ProxyResource": { - "description": "The resource model definition for a ARM proxy resource. It will have everything other than required location and tags", + "title": "Proxy Resource", + "description": "The resource model definition for a Azure Resource Manager proxy resource. It will not have tags and a location", "allOf": [ { "$ref": "#/definitions/Resource" @@ -92,7 +97,7 @@ "x-ms-mutability": [ "read" ], - "description": "Fully qualified resource Id for the resource. Ex - /subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/{resourceProviderNamespace}/{resourceType}/{resourceName}" + "description": "Fully qualified resource ID for the resource. Ex - /subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/{resourceProviderNamespace}/{resourceType}/{resourceName}" }, "name": { "readOnly": true, @@ -105,7 +110,7 @@ "x-ms-mutability": [ "read" ], - "description": "The type of the resource. Ex- Microsoft.Compute/virtualMachines or Microsoft.Storage/storageAccounts.." + "description": "The type of the resource. E.g. \"Microsoft.Compute/virtualMachines\" or \"Microsoft.Storage/storageAccounts\"" }, "location": { "type": "string", @@ -270,6 +275,8 @@ ] }, "ErrorResponse": { + "title": "Error Response", + "description": "Common error response for all Azure Resource Manager APIs to return error details for failed operations. (This also follows the OData error response format.)", "properties": { "code": { "readOnly": true, @@ -302,8 +309,7 @@ }, "description": "The error additional info." } - }, - "description": "The resource management error response." + } }, "ErrorAdditionalInfo": { "properties": { @@ -320,6 +326,92 @@ }, "description": "The resource management error additional info." }, + "Operation": { + "title": "REST API Operation", + "description": "Details of a REST API operation, returned from the Resource Provider Operations API", + "type": "object", + "properties": { + "name": { + "description": "The name of the operation, as per Resource-Based Access Control (RBAC). Examples: \"Microsoft.Compute/virtualMachines/write\", \"Microsoft.Compute/virtualMachines/capture/action\"", + "type": "string", + "readOnly": true + }, + "isDataAction": { + "description": "Whether the operation applies to data-plane. This is \"true\" for data-plane operations and \"false\" for ARM/control-plane operations.", + "type": "boolean", + "readOnly": true + }, + "display": { + "description": "Localized display information for this particular operation.", + "properties": { + "provider": { + "description": "The localized friendly form of the resource provider name, e.g. \"Microsoft Monitoring Insights\" or \"Microsoft Compute\".", + "type": "string", + "readOnly": true + }, + "resource": { + "description": "The localized friendly name of the resource type related to this operation. E.g. \"Virtual Machines\" or \"Job Schedule Collections\".", + "type": "string", + "readOnly": true + }, + "operation": { + "description": "The concise, localized friendly name for the operation; suitable for dropdowns. E.g. \"Create or Update Virtual Machine\", \"Restart Virtual Machine\".", + "type": "string", + "readOnly": true + }, + "description": { + "description": "The short, localized friendly description of the operation; suitable for tool tips and detailed views.", + "type": "string", + "readOnly": true + } + } + }, + "origin": { + "description": "The intended executor of the operation; as in Resource Based Access Control (RBAC) and audit logs UX. Default value is \"user,system\"", + "type": "string", + "readOnly": true, + "enum": [ + "user", + "system", + "user,system" + ], + "x-ms-enum": { + "name": "Origin", + "modelAsString": true + } + }, + "actionType": { + "description": "Enum. Indicates the action type. \"Internal\" refers to actions that are for internal only APIs.", + "type": "string", + "readOnly": true, + "enum": [ + "Internal" + ], + "x-ms-enum": { + "name": "ActionType", + "modelAsString": true + } + } + } + }, + "OperationListResult": { + "description": "A list of REST API operations supported by an Azure Resource Provider. It contains an URL link to get the next set of results.", + "properties": { + "value": { + "type": "array", + "items": { + "$ref": "#/definitions/Operation" + }, + "description": "List of operations supported by the resource provider", + "readOnly": true + }, + "nextLink": { + "type": "string", + "description": "URL to get the next set of operation list results (if there are any).", + "readOnly": true + } + } + }, "locationData": { "description": "Metadata pertaining to the geographic location of the resource.", "type": "object", @@ -429,7 +521,7 @@ "type": "string" }, "identity": { - "description": "The client id of the identity which will be used to access key vault.", + "description": "The client ID of the identity which will be used to access key vault.", "type": "string" } } diff --git a/specification/common-types/resource-management/v2/types.json b/specification/common-types/resource-management/v2/types.json index 7ef5fc2bb4a0..b350d61b7e98 100644 --- a/specification/common-types/resource-management/v2/types.json +++ b/specification/common-types/resource-management/v2/types.json @@ -7,11 +7,12 @@ "paths": {}, "definitions": { "Resource": { + "description": "Common fields that are returned in the response for all Azure Resource Manager resources", "properties": { "id": { "readOnly": true, "type": "string", - "description": "Fully qualified resource Id for the resource. Ex - /subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/{resourceProviderNamespace}/{resourceType}/{resourceName}" + "description": "Fully qualified resource ID for the resource. Ex - /subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/{resourceProviderNamespace}/{resourceType}/{resourceName}" }, "name": { "readOnly": true, @@ -21,15 +22,14 @@ "type": { "readOnly": true, "type": "string", - "description": "The type of the resource. Ex- Microsoft.Compute/virtualMachines or Microsoft.Storage/storageAccounts." + "description": "The type of the resource. E.g. \"Microsoft.Compute/virtualMachines\" or \"Microsoft.Storage/storageAccounts\"" } }, - "description": "The resource model definition for a ARM tracked top level resource", "x-ms-azure-resource": true }, "AzureEntityResource": { "x-ms-client-name": "AzureEntityResource", - "description": "The resource model definition for a Azure Resource Manager resource with an etag.", + "description": "The resource model definition for an Azure Resource Manager resource with an etag.", "properties": { "etag": { "type": "string", @@ -44,7 +44,7 @@ ] }, "TrackedResource": { - "description": "The resource model definition for a ARM tracked top level resource", + "description": "The resource model definition for an Azure Resource Manager tracked top level resource", "properties": { "tags": { "type": "object", @@ -77,7 +77,7 @@ ] }, "ProxyResource": { - "description": "The resource model definition for a ARM proxy resource. It will have everything other than required location and tags", + "description": "The resource model definition for an Azure Resource Manager proxy resource. It will have everything other than required location and tags", "allOf": [ { "$ref": "#/definitions/Resource" @@ -93,7 +93,7 @@ "x-ms-mutability": [ "read" ], - "description": "Fully qualified resource Id for the resource. Ex - /subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/{resourceProviderNamespace}/{resourceType}/{resourceName}" + "description": "Fully qualified resource ID for the resource. Ex - /subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/{resourceProviderNamespace}/{resourceType}/{resourceName}" }, "name": { "readOnly": true, @@ -106,7 +106,7 @@ "x-ms-mutability": [ "read" ], - "description": "The type of the resource. Ex- Microsoft.Compute/virtualMachines or Microsoft.Storage/storageAccounts.." + "description": "The type of the resource. E.g. \"Microsoft.Compute/virtualMachines\" or \"Microsoft.Storage/storageAccounts\"" }, "location": { "type": "string", @@ -123,7 +123,7 @@ "create", "update" ], - "description": "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." + "description": "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." }, "kind": { "type": "string", @@ -207,7 +207,7 @@ "capacity": { "type": "integer", "format": "int32", - "description": "If the SKU supports scale out/in then the capacity integer should be included. If scale out/in is not possible for the resource this may be omitted." + "description": "If the SKU supports scale out/in then the capacity integer indicates the current scaling-factor of the resource. If scale out/in is not possible for the resource this may be omitted." } }, "required": [ @@ -327,6 +327,91 @@ }, "description": "The resource management error additional info." }, + "Operation": { + "description": "Details of a REST API operation, returned from the Resource Provider Operations API", + "type": "object", + "properties": { + "name": { + "description": "The name of the operation, as per Resource-Based Access Control (RBAC). Examples: \"Microsoft.Compute/virtualMachines/write\", \"Microsoft.Compute/virtualMachines/capture/action\"", + "type": "string", + "readOnly": true + }, + "isDataAction": { + "description": "Whether the operation applies to data-plane. This is \"true\" for data-plane operations and \"false\" for ARM/control-plane operations.", + "type": "boolean", + "readOnly": true + }, + "display": { + "description": "Localized display information for this particular operation.", + "properties": { + "provider": { + "description": "The localized friendly form of the resource provider name, e.g. \"Microsoft Monitoring Insights\" or \"Microsoft Compute\".", + "type": "string", + "readOnly": true + }, + "resource": { + "description": "The localized friendly name of the resource type related to this operation. E.g. \"Virtual Machines\" or \"Job Schedule Collections\".", + "type": "string", + "readOnly": true + }, + "operation": { + "description": "The concise, localized friendly name for the operation; suitable for dropdowns. E.g. \"Create or Update Virtual Machine\", \"Restart Virtual Machine\".", + "type": "string", + "readOnly": true + }, + "description": { + "description": "The short, localized friendly description of the operation; suitable for tool tips and detailed views.", + "type": "string", + "readOnly": true + } + } + }, + "origin": { + "description": "The intended executor of the operation; as in Resource Based Access Control (RBAC) and audit logs UX. Default value is \"user,system\"", + "type": "string", + "readOnly": true, + "enum": [ + "user", + "system", + "user,system" + ], + "x-ms-enum": { + "name": "Origin", + "modelAsString": true + } + }, + "actionType": { + "description": "Enum. Indicates the action type. \"Internal\" refers to actions that are for internal only APIs.", + "type": "string", + "readOnly": true, + "enum": [ + "Internal" + ], + "x-ms-enum": { + "name": "ActionType", + "modelAsString": true + } + } + } + }, + "OperationListResult": { + "description": "A list of REST API operations supported by an Azure Resource Provider. It contains an URL link to get the next set of results.", + "properties": { + "value": { + "type": "array", + "items": { + "$ref": "#/definitions/Operation" + }, + "description": "List of operations supported by the resource provider", + "readOnly": true + }, + "nextLink": { + "type": "string", + "description": "URL to get the next set of operation list results (if there are any).", + "readOnly": true + } + } + }, "locationData": { "description": "Metadata pertaining to the geographic location of the resource.", "type": "object", @@ -436,7 +521,7 @@ "type": "string" }, "identity": { - "description": "The client id of the identity which will be used to access key vault.", + "description": "The client ID of the identity which will be used to access key vault.", "type": "string" } }