diff --git a/custom-words.txt b/custom-words.txt index 61b5662dacd2..ee1d5930e087 100644 --- a/custom-words.txt +++ b/custom-words.txt @@ -1,4 +1,4 @@ -A128CBCPAD +A128CBCPAD A192CBCPAD A256CBCPAD AADDS @@ -2702,4 +2702,5 @@ Skolt Thangmi Tuvan Uyghur -Paramter \ No newline at end of file +Paramter +widget's diff --git a/specification/contosowidgetmanager/Contoso.WidgetManager.Shared/main.cadl b/specification/contosowidgetmanager/Contoso.WidgetManager.Shared/main.cadl new file mode 100644 index 000000000000..ce9d59382a69 --- /dev/null +++ b/specification/contosowidgetmanager/Contoso.WidgetManager.Shared/main.cadl @@ -0,0 +1,8 @@ +@doc("Faked shared model") +model FakedSharedModel { + @doc("The tag.") + tag: string; + + @doc("The created date.") + createdDate: zonedDateTime; +} \ No newline at end of file diff --git a/specification/contosowidgetmanager/Contoso.WidgetManager/cadl-project.yaml b/specification/contosowidgetmanager/Contoso.WidgetManager/cadl-project.yaml new file mode 100644 index 000000000000..b67f345cb4de --- /dev/null +++ b/specification/contosowidgetmanager/Contoso.WidgetManager/cadl-project.yaml @@ -0,0 +1,38 @@ +parameters: + "python-sdk-folder": + default: "{cwd}/azure-sdk-for-python/" + "java-sdk-folder": + default: "{cwd}/azure-sdk-for-java/" + "js-sdk-folder": + default: "{cwd}/azure-sdk-for-js/" + "csharp-sdk-folder": + default: "{cwd}/azure-sdk-for-csharp/" + "service-directory-name": + default: "contosowidgetmanager" +emit: + - "@azure-tools/cadl-autorest" +options: + "@azure-tools/cadl-autorest": + output-file: widgets.json + azure-resource-provider-folder: ../../../../data-plane + examples-directory: ./examples + "@azure-tools/cadl-python": + "package-name": "azure-contosowidgetmanager" + "emitter-output-dir": "{python-sdk-folder}/sdk/{service-directory-name}/{package-name}" + "package-mode": "dataplane" + "@azure-tools/cadl-csharp": + namespace: Azure.Contoso.Widgetmanager + clear-output-folder: true + model-namespace: false + "emitter-output-dir": "{csharp-sdk-folder}/sdk/{service-directory-name}/{namespace}/src" + "@azure-tools/cadl-typescript": + "emitter-output-dir": "{js-sdk-folder}/sdk/{service-directory-name}/contosowidgetmanager-rest" + generateMetadata: true + generateTest: true + azureSdkForJs: true + packageDetails: + name: "@azure-rest/contosowidgetmanager-rest" + description: "Contoso WidgetManager Service" + "@azure-tools/cadl-java": + "emitter-output-dir": "{java-sdk-folder}/sdk/{service-directory-name}/azure-contoso-widgetmanager" + namespace: com.azure.contoso.widgetmanager diff --git a/specification/contosowidgetmanager/Contoso.WidgetManager/examples/2022-11-01-preview/Widgets_DeleteWidgetSample.json b/specification/contosowidgetmanager/Contoso.WidgetManager/examples/2022-11-01-preview/Widgets_DeleteWidgetSample.json new file mode 100644 index 000000000000..402fccb6ae2a --- /dev/null +++ b/specification/contosowidgetmanager/Contoso.WidgetManager/examples/2022-11-01-preview/Widgets_DeleteWidgetSample.json @@ -0,0 +1,25 @@ +{ + "operationId": "Widgets_DeleteWidget", + "title": "Delete widget by widget name using long-running operation.", + "parameters": { + "api-version": "2022-11-01-preview", + "widgetName": "searchbox" + }, + "responses": { + "204": {}, + "202": { + "headers": { + "location": "https://contosowidgetmanager.azure.com/operations/00000000-0000-0000-0000-000000000123/result?api-version=2022-11-01-preview", + "operation-location": "https://contosowidgetmanager.azure.com/operations/00000000-0000-0000-0000-000000000123?api-version=2022-11-01-preview" + } + }, + "default": { + "body": { + "error": { + "code": "Error code", + "message": "Error message" + } + } + } + } +} diff --git a/specification/contosowidgetmanager/Contoso.WidgetManager/examples/2022-11-01-preview/Widgets_GetWidgetSample.json b/specification/contosowidgetmanager/Contoso.WidgetManager/examples/2022-11-01-preview/Widgets_GetWidgetSample.json new file mode 100644 index 000000000000..907a5b8cbef2 --- /dev/null +++ b/specification/contosowidgetmanager/Contoso.WidgetManager/examples/2022-11-01-preview/Widgets_GetWidgetSample.json @@ -0,0 +1,24 @@ +{ + "operationId": "Widgets_GetWidget", + "title": "Get widget by widget name.", + "parameters": { + "api-version": "2022-11-01-preview", + "widgetName": "searchbox" + }, + "responses": { + "200": { + "body": { + "name": "bingsearch", + "manufacturerId": "a-22-01" + } + }, + "default": { + "body": { + "error": { + "code": "Error code", + "message": "Error message" + } + } + } + } +} diff --git a/specification/contosowidgetmanager/Contoso.WidgetManager/main.cadl b/specification/contosowidgetmanager/Contoso.WidgetManager/main.cadl new file mode 100644 index 000000000000..d7521d635d85 --- /dev/null +++ b/specification/contosowidgetmanager/Contoso.WidgetManager/main.cadl @@ -0,0 +1,59 @@ +import "@cadl-lang/rest"; +import "@cadl-lang/versioning"; +import "@azure-tools/cadl-azure-core"; +import "../Contoso.WidgetManager.Shared"; + +using Cadl.Http; +using Cadl.Rest; +using Cadl.Versioning; +using Azure.Core; + +@service({ + title: "Contoso Widget Manager", + }) +@versioned(Contoso.WidgetManager.Versions) +@versionedDependency([[Contoso.WidgetManager.Versions.v2022_11_01_Preview, Azure.Core.Versions.v1_0_Preview_1]]) +namespace Azure.Contoso.WidgetManager; + +enum Versions { + v2022_11_01_Preview: "2022-11-01-preview", +} + +@doc("A widget.") +@resource("widgets") +model Widget { + @key("widgetName") + @doc("The widget name.") + @visibility("read") + name: string; + + @doc("The ID of the widget's manufacturer.") + manufacturerId: string; + + @doc("The faked shared model.") + sharedModel?: FakedSharedModel; +} + +interface Widgets { + @doc("Fetch a Widget by name.") + getWidget is ResourceRead; + + @doc("Gets status of a Widget operation.") + getWidgetOperationStatus is GetResourceOperationStatus; + + @doc("Creates or updates a Widget asynchronously.") + @pollingOperation(Widgets.getWidgetOperationStatus) + createOrUpdateWidget is LongRunningResourceCreateOrUpdate; + + @doc("Delete a Widget asynchronously.") + @pollingOperation(Widgets.getWidgetOperationStatus) + deleteWidget is LongRunningResourceDelete; + + @doc("List Widget resources") + listWidgets is ResourceList< + Widget, + { + parameters: StandardListQueryParameters & SelectQueryParameter; + } + >; +} \ No newline at end of file diff --git a/specification/contosowidgetmanager/Contoso.WidgetManager/package.json b/specification/contosowidgetmanager/Contoso.WidgetManager/package.json new file mode 100644 index 000000000000..4d8fd4a967a1 --- /dev/null +++ b/specification/contosowidgetmanager/Contoso.WidgetManager/package.json @@ -0,0 +1,7 @@ +{ + "name": "contoso-widget-manager", + "dependencies": { + "@azure-tools/cadl-autorest": "latest" + }, + "private": true +} diff --git a/specification/contosowidgetmanager/data-plane/Azure.Contoso.WidgetManager/preview/2022-11-01-preview/examples/Widgets_DeleteWidgetSample.json b/specification/contosowidgetmanager/data-plane/Azure.Contoso.WidgetManager/preview/2022-11-01-preview/examples/Widgets_DeleteWidgetSample.json new file mode 100644 index 000000000000..402fccb6ae2a --- /dev/null +++ b/specification/contosowidgetmanager/data-plane/Azure.Contoso.WidgetManager/preview/2022-11-01-preview/examples/Widgets_DeleteWidgetSample.json @@ -0,0 +1,25 @@ +{ + "operationId": "Widgets_DeleteWidget", + "title": "Delete widget by widget name using long-running operation.", + "parameters": { + "api-version": "2022-11-01-preview", + "widgetName": "searchbox" + }, + "responses": { + "204": {}, + "202": { + "headers": { + "location": "https://contosowidgetmanager.azure.com/operations/00000000-0000-0000-0000-000000000123/result?api-version=2022-11-01-preview", + "operation-location": "https://contosowidgetmanager.azure.com/operations/00000000-0000-0000-0000-000000000123?api-version=2022-11-01-preview" + } + }, + "default": { + "body": { + "error": { + "code": "Error code", + "message": "Error message" + } + } + } + } +} diff --git a/specification/contosowidgetmanager/data-plane/Azure.Contoso.WidgetManager/preview/2022-11-01-preview/examples/Widgets_GetWidgetSample.json b/specification/contosowidgetmanager/data-plane/Azure.Contoso.WidgetManager/preview/2022-11-01-preview/examples/Widgets_GetWidgetSample.json new file mode 100644 index 000000000000..907a5b8cbef2 --- /dev/null +++ b/specification/contosowidgetmanager/data-plane/Azure.Contoso.WidgetManager/preview/2022-11-01-preview/examples/Widgets_GetWidgetSample.json @@ -0,0 +1,24 @@ +{ + "operationId": "Widgets_GetWidget", + "title": "Get widget by widget name.", + "parameters": { + "api-version": "2022-11-01-preview", + "widgetName": "searchbox" + }, + "responses": { + "200": { + "body": { + "name": "bingsearch", + "manufacturerId": "a-22-01" + } + }, + "default": { + "body": { + "error": { + "code": "Error code", + "message": "Error message" + } + } + } + } +} diff --git a/specification/contosowidgetmanager/data-plane/Azure.Contoso.WidgetManager/preview/2022-11-01-preview/widgets.json b/specification/contosowidgetmanager/data-plane/Azure.Contoso.WidgetManager/preview/2022-11-01-preview/widgets.json new file mode 100644 index 000000000000..87247f134532 --- /dev/null +++ b/specification/contosowidgetmanager/data-plane/Azure.Contoso.WidgetManager/preview/2022-11-01-preview/widgets.json @@ -0,0 +1,553 @@ +{ + "swagger": "2.0", + "info": { + "title": "Contoso Widget Manager", + "version": "2022-11-01-preview", + "x-cadl-generated": [ + { + "emitter": "@azure-tools/cadl-autorest" + } + ] + }, + "schemes": [ + "https" + ], + "produces": [ + "application/json" + ], + "consumes": [ + "application/json" + ], + "tags": [], + "paths": { + "/widgets": { + "get": { + "operationId": "Widgets_ListWidgets", + "description": "List Widget resources", + "parameters": [ + { + "$ref": "#/parameters/Azure.Core.TopQueryParameter" + }, + { + "$ref": "#/parameters/Azure.Core.SkipQueryParameter" + }, + { + "$ref": "#/parameters/Azure.Core.MaxPageSizeQueryParameter" + }, + { + "$ref": "#/parameters/Azure.Core.SelectQueryParameter" + }, + { + "$ref": "#/parameters/Azure.Core.Foundations.ApiVersionParameter" + } + ], + "responses": { + "200": { + "description": "The request has succeeded.", + "schema": { + "type": "object", + "properties": { + "value": { + "type": "array", + "items": { + "$ref": "#/definitions/Widget" + }, + "x-ms-identifiers": [], + "x-cadl-name": "Widget[]", + "description": "The Widget items on this page" + }, + "nextLink": { + "type": "string", + "format": "uri", + "description": "The link to the next page of items", + "x-cadl-name": "Rest.ResourceLocation" + } + }, + "description": "Paged collection of Widget items", + "required": [ + "value" + ], + "x-cadl-name": "Azure.Core.Foundations.CustomPage" + } + }, + "default": { + "description": "An unexpected error response.", + "schema": { + "$ref": "#/definitions/Azure.Core.Foundations.ErrorResponse" + } + } + }, + "x-ms-pageable": { + "nextLinkName": "nextLink" + } + } + }, + "/widgets/{widgetName}": { + "get": { + "operationId": "Widgets_GetWidget", + "description": "Fetch a Widget by name.", + "parameters": [ + { + "name": "widgetName", + "in": "path", + "required": true, + "description": "The widget name.", + "type": "string" + }, + { + "$ref": "#/parameters/Azure.Core.Foundations.ApiVersionParameter" + } + ], + "responses": { + "200": { + "description": "The request has succeeded.", + "schema": { + "$ref": "#/definitions/Widget" + } + }, + "default": { + "description": "An unexpected error response.", + "schema": { + "$ref": "#/definitions/Azure.Core.Foundations.ErrorResponse" + } + } + }, + "x-ms-examples": { + "Get widget by widget name.": { + "$ref": "./examples/Widgets_GetWidgetSample.json" + } + } + }, + "patch": { + "operationId": "Widgets_CreateOrUpdateWidget", + "description": "Creates or updates a Widget asynchronously.", + "parameters": [ + { + "name": "widgetName", + "in": "path", + "required": true, + "description": "The widget name.", + "type": "string" + }, + { + "$ref": "#/parameters/Azure.Core.Foundations.ApiVersionParameter" + }, + { + "name": "body", + "in": "body", + "schema": { + "type": "object", + "properties": { + "manufacturerId": { + "type": "string", + "description": "The ID of the widget's manufacturer." + }, + "sharedModel": { + "$ref": "#/definitions/FakedSharedModel", + "description": "The faked shared model." + } + }, + "description": "The template for adding optional properties.", + "x-cadl-name": "Azure.Core.Foundations.ResourceCreateOrUpdateModel" + } + } + ], + "responses": { + "200": { + "description": "The request has succeeded.", + "headers": { + "Operation-Location": { + "description": "The location of an instance of OperationStatus", + "type": "string", + "format": "uri" + } + }, + "schema": { + "type": "object", + "properties": { + "name": { + "type": "string", + "description": "The widget name.", + "readOnly": true + }, + "manufacturerId": { + "type": "string", + "description": "The ID of the widget's manufacturer." + }, + "sharedModel": { + "$ref": "#/definitions/FakedSharedModel", + "description": "The faked shared model." + } + }, + "required": [ + "name", + "manufacturerId" + ], + "x-cadl-name": "Azure.Core.Foundations.ResourceOkResponse" + } + }, + "201": { + "description": "The request has succeeded and a new resource has been created as a result.", + "headers": { + "Operation-Location": { + "description": "The location of an instance of OperationStatus", + "type": "string", + "format": "uri" + } + }, + "schema": { + "type": "object", + "properties": { + "name": { + "type": "string", + "description": "The widget name.", + "readOnly": true + }, + "manufacturerId": { + "type": "string", + "description": "The ID of the widget's manufacturer." + }, + "sharedModel": { + "$ref": "#/definitions/FakedSharedModel", + "description": "The faked shared model." + } + }, + "description": "A resource was successfully created.", + "required": [ + "name", + "manufacturerId" + ], + "x-cadl-name": "Azure.Core.Foundations.ResourceCreatedResponse" + } + }, + "default": { + "description": "An unexpected error response.", + "schema": { + "$ref": "#/definitions/Azure.Core.Foundations.ErrorResponse" + } + } + }, + "consumes": [ + "application/merge-patch+json" + ] + }, + "delete": { + "operationId": "Widgets_DeleteWidget", + "description": "Delete a Widget asynchronously.", + "parameters": [ + { + "name": "widgetName", + "in": "path", + "required": true, + "description": "The widget name.", + "type": "string" + }, + { + "$ref": "#/parameters/Azure.Core.Foundations.ApiVersionParameter" + } + ], + "responses": { + "202": { + "description": "The request has been accepted for processing, but processing has not yet completed.", + "headers": { + "Operation-Location": { + "description": "The location of an instance of OperationStatus", + "type": "string", + "format": "uri" + } + }, + "schema": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "The unique ID of the operation." + }, + "status": { + "$ref": "#/definitions/Azure.Core.Foundations.OperationState", + "description": "The status of the operation" + }, + "error": { + "$ref": "#/definitions/Azure.Core.Foundations.Error", + "description": "Error object that describes the error when status is \"Failed\"." + } + }, + "required": [ + "id", + "status" + ], + "x-cadl-name": "Azure.Core.Foundations.AcceptedResponse" + } + }, + "default": { + "description": "An unexpected error response.", + "schema": { + "$ref": "#/definitions/Azure.Core.Foundations.ErrorResponse" + } + } + }, + "x-ms-examples": { + "Delete widget by widget name using long-running operation.": { + "$ref": "./examples/Widgets_DeleteWidgetSample.json" + } + } + } + }, + "/widgets/{widgetName}/operations/{operationId}": { + "get": { + "operationId": "Widgets_GetWidgetOperationStatus", + "description": "Gets status of a Widget operation.", + "parameters": [ + { + "name": "widgetName", + "in": "path", + "required": true, + "description": "The widget name.", + "type": "string" + }, + { + "name": "operationId", + "in": "path", + "required": true, + "description": "The unique ID of the operation.", + "type": "string" + }, + { + "$ref": "#/parameters/Azure.Core.Foundations.ApiVersionParameter" + } + ], + "responses": { + "200": { + "description": "The request has succeeded.", + "schema": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "The unique ID of the operation." + }, + "status": { + "$ref": "#/definitions/Azure.Core.Foundations.OperationState", + "description": "The status of the operation" + }, + "error": { + "$ref": "#/definitions/Azure.Core.Foundations.Error", + "description": "Error object that describes the error when status is \"Failed\"." + }, + "result": { + "$ref": "#/definitions/Widget", + "description": "The result of the operation." + }, + "widgetName": { + "type": "string", + "description": "The widget name." + } + }, + "required": [ + "id", + "status", + "widgetName" + ], + "x-cadl-name": "(anonymous model)" + } + }, + "default": { + "description": "An unexpected error response.", + "schema": { + "$ref": "#/definitions/Azure.Core.Foundations.ErrorResponse" + } + } + } + } + } + }, + "definitions": { + "Azure.Core.Foundations.Error": { + "type": "object", + "properties": { + "code": { + "type": "string", + "description": "One of a server-defined set of error codes." + }, + "message": { + "type": "string", + "description": "A human-readable representation of the error." + }, + "target": { + "type": "string", + "description": "The target of the error." + }, + "details": { + "type": "array", + "items": { + "$ref": "#/definitions/Azure.Core.Foundations.Error" + }, + "x-ms-identifiers": [], + "x-cadl-name": "Azure.Core.Foundations.Error[]", + "description": "An array of details about specific errors that led to this reported error." + }, + "innererror": { + "$ref": "#/definitions/Azure.Core.Foundations.InnerError", + "description": "An object containing more specific information than the current object about the error." + } + }, + "description": "The error object.", + "required": [ + "code", + "message", + "details" + ] + }, + "Azure.Core.Foundations.ErrorResponse": { + "type": "object", + "properties": { + "error": { + "$ref": "#/definitions/Azure.Core.Foundations.Error", + "description": "The error object." + } + }, + "description": "A response containing error details.", + "required": [ + "error" + ] + }, + "Azure.Core.Foundations.InnerError": { + "type": "object", + "properties": { + "code": { + "type": "string", + "description": "One of a server-defined set of error codes." + }, + "innererror": { + "$ref": "#/definitions/Azure.Core.Foundations.InnerError", + "description": "Inner error." + } + }, + "description": "An object containing more specific information about the error. As per Microsoft One API guidelines - https://github.com/Microsoft/api-guidelines/blob/vNext/Guidelines.md#7102-error-condition-responses.", + "required": [ + "code" + ] + }, + "Azure.Core.Foundations.OperationState": { + "type": "string", + "enum": [ + "InProgress", + "Succeeded", + "Failed", + "Canceled" + ], + "x-ms-enum": { + "name": "OperationState", + "modelAsString": true + } + }, + "FakedSharedModel": { + "type": "object", + "properties": { + "tag": { + "type": "string", + "description": "The tag." + }, + "createdDate": { + "type": "string", + "format": "date-time", + "description": "The created date." + } + }, + "description": "Faked shared model", + "required": [ + "tag", + "createdDate" + ] + }, + "Versions": { + "type": "string", + "enum": [ + "2022-11-01-preview" + ], + "x-ms-enum": { + "name": "Versions", + "modelAsString": true, + "values": [ + { + "name": "v2022_11_01_Preview", + "value": "2022-11-01-preview" + } + ] + } + }, + "Widget": { + "type": "object", + "properties": { + "name": { + "type": "string", + "description": "The widget name.", + "readOnly": true + }, + "manufacturerId": { + "type": "string", + "description": "The ID of the widget's manufacturer." + }, + "sharedModel": { + "$ref": "#/definitions/FakedSharedModel", + "description": "The faked shared model." + } + }, + "description": "A widget.", + "required": [ + "name", + "manufacturerId" + ] + } + }, + "parameters": { + "Azure.Core.Foundations.ApiVersionParameter": { + "name": "api-version", + "in": "query", + "required": true, + "description": "The API version to use for this operation.", + "x-ms-client-name": "apiVersion", + "minLength": 1, + "type": "string", + "x-ms-parameter-location": "method" + }, + "Azure.Core.MaxPageSizeQueryParameter": { + "name": "maxpagesize", + "in": "query", + "required": false, + "description": "The maximum number of result items per page.", + "type": "integer", + "format": "int32", + "x-ms-parameter-location": "method" + }, + "Azure.Core.SelectQueryParameter": { + "name": "select", + "in": "query", + "required": false, + "description": "Select the specified fields to be included in the response.", + "type": "array", + "items": { + "type": "string" + }, + "x-ms-parameter-location": "method" + }, + "Azure.Core.SkipQueryParameter": { + "name": "skip", + "in": "query", + "required": false, + "description": "The number of result items to skip.", + "type": "integer", + "format": "int32", + "x-ms-parameter-location": "method" + }, + "Azure.Core.TopQueryParameter": { + "name": "top", + "in": "query", + "required": false, + "description": "The number of result items to return.", + "type": "integer", + "format": "int32", + "x-ms-parameter-location": "method" + } + } +}