From b60da392c1e81998354e4269dc61efa997c2d545 Mon Sep 17 00:00:00 2001 From: Alfred Sin Date: Tue, 29 Oct 2019 09:30:03 -0700 Subject: [PATCH] Update serial console swagger (#7444) * Update serial console swagger 10/9/2019 * Make operationId casing consistent * Fix formatting. Also, default is not a parameter * Address build errors * Describe GetOperations output * Clarify scale set instance * Add default back as a parameter, update examples accordingly * Add x-ms-parameter-location * rename GetSerialConsoleDisabledResult to SerialConsoleStatus and update example accordingly --- .../examples/DisableConsoleExamples.json | 6 +- .../examples/EnableConsoleExamples.json | 6 +- .../examples/GetOperationsExample.json | 36 +++- ...Examples.json => SerialConsoleStatus.json} | 6 +- .../stable/2018-05-01/serialconsole.json | 196 ++++++++++-------- 5 files changed, 155 insertions(+), 95 deletions(-) rename specification/serialconsole/resource-manager/Microsoft.SerialConsole/stable/2018-05-01/examples/{GetConsoleDisabledExamples.json => SerialConsoleStatus.json} (63%) diff --git a/specification/serialconsole/resource-manager/Microsoft.SerialConsole/stable/2018-05-01/examples/DisableConsoleExamples.json b/specification/serialconsole/resource-manager/Microsoft.SerialConsole/stable/2018-05-01/examples/DisableConsoleExamples.json index 550047d40f9a..35412a197eb8 100644 --- a/specification/serialconsole/resource-manager/Microsoft.SerialConsole/stable/2018-05-01/examples/DisableConsoleExamples.json +++ b/specification/serialconsole/resource-manager/Microsoft.SerialConsole/stable/2018-05-01/examples/DisableConsoleExamples.json @@ -10,10 +10,12 @@ "disabled": true } }, - "default": { + "404": { "body": { - "errorMessage": "This message will contain details on failure" + "code": "SubscriptionNotFound", + "message": "The subscription '00000000-00000-0000-0000-000000000000' could not be found." } } } } + diff --git a/specification/serialconsole/resource-manager/Microsoft.SerialConsole/stable/2018-05-01/examples/EnableConsoleExamples.json b/specification/serialconsole/resource-manager/Microsoft.SerialConsole/stable/2018-05-01/examples/EnableConsoleExamples.json index 9f4e66b11dbc..6623955b79d6 100644 --- a/specification/serialconsole/resource-manager/Microsoft.SerialConsole/stable/2018-05-01/examples/EnableConsoleExamples.json +++ b/specification/serialconsole/resource-manager/Microsoft.SerialConsole/stable/2018-05-01/examples/EnableConsoleExamples.json @@ -10,10 +10,12 @@ "disabled": false } }, - "default": { + "404": { "body": { - "errorMessage": "This message will contain details on failure" + "code": "SubscriptionNotFound", + "message": "The subscription '00000000-00000-0000-0000-000000000000' could not be found." } } } } + diff --git a/specification/serialconsole/resource-manager/Microsoft.SerialConsole/stable/2018-05-01/examples/GetOperationsExample.json b/specification/serialconsole/resource-manager/Microsoft.SerialConsole/stable/2018-05-01/examples/GetOperationsExample.json index f9c5bb42b637..afa01db38fe7 100644 --- a/specification/serialconsole/resource-manager/Microsoft.SerialConsole/stable/2018-05-01/examples/GetOperationsExample.json +++ b/specification/serialconsole/resource-manager/Microsoft.SerialConsole/stable/2018-05-01/examples/GetOperationsExample.json @@ -1,12 +1,42 @@ { "parameters": { - "api-version": "2018-05-01", - "subscriptionId": "00000000-00000-0000-0000-000000000000" + "api-version": "2018-05-01" }, "responses": { "200": { "body": { - "value": "Get operations response" + "value": [ + { + "name": "Microsoft.SerialConsole/consoleServices/read", + "isDataAction": "false", + "display": { + "provider": "Microsoft.SerialConsole", + "resource": "Serial Console instance", + "operation": "Default", + "description": "Retrieves the current subscription state" + } + }, + { + "name": "Microsoft.SerialConsole/consoleServices/disableConsole/action", + "isDataAction": "false", + "display": { + "provider": "Microsoft.SerialConsole", + "resource": "Serial Console instance", + "operation": "Disable Console", + "description": "Disable Serial Console for a subscription" + } + }, + { + "name": "Microsoft.SerialConsole/consoleServices/enableConsole/action", + "isDataAction": "false", + "display": { + "provider": "Microsoft.SerialConsole", + "resource": "Serial Console instance", + "operation": "Enable Console", + "description": "Enable Serial Console for a subscription" + } + } + ] } } } diff --git a/specification/serialconsole/resource-manager/Microsoft.SerialConsole/stable/2018-05-01/examples/GetConsoleDisabledExamples.json b/specification/serialconsole/resource-manager/Microsoft.SerialConsole/stable/2018-05-01/examples/SerialConsoleStatus.json similarity index 63% rename from specification/serialconsole/resource-manager/Microsoft.SerialConsole/stable/2018-05-01/examples/GetConsoleDisabledExamples.json rename to specification/serialconsole/resource-manager/Microsoft.SerialConsole/stable/2018-05-01/examples/SerialConsoleStatus.json index 4927ca78fac7..35412a197eb8 100644 --- a/specification/serialconsole/resource-manager/Microsoft.SerialConsole/stable/2018-05-01/examples/GetConsoleDisabledExamples.json +++ b/specification/serialconsole/resource-manager/Microsoft.SerialConsole/stable/2018-05-01/examples/SerialConsoleStatus.json @@ -10,10 +10,12 @@ "disabled": true } }, - "default": { + "404": { "body": { - "errorMessage": "This message contains details on failure" + "code": "SubscriptionNotFound", + "message": "The subscription '00000000-00000-0000-0000-000000000000' could not be found." } } } } + diff --git a/specification/serialconsole/resource-manager/Microsoft.SerialConsole/stable/2018-05-01/serialconsole.json b/specification/serialconsole/resource-manager/Microsoft.SerialConsole/stable/2018-05-01/serialconsole.json index c036e0aa80aa..399166a01812 100644 --- a/specification/serialconsole/resource-manager/Microsoft.SerialConsole/stable/2018-05-01/serialconsole.json +++ b/specification/serialconsole/resource-manager/Microsoft.SerialConsole/stable/2018-05-01/serialconsole.json @@ -3,7 +3,7 @@ "info": { "title": "MicrosoftSerialConsoleClient", "version": "2018-05-01", - "description": "Azure Virtual Machine Serial Console allows you to access serial console of a Virtual Machine" + "description": "The Azure Serial Console allows you to access the serial console of a Virtual Machine or VM scale set instance" }, "host": "management.azure.com", "schemes": [ @@ -34,18 +34,13 @@ } }, "paths": { - "/subscriptions/{subscriptionId}/providers/Microsoft.SerialConsole/operations": { + "/providers/Microsoft.SerialConsole/operations": { "get": { "tags": [ "SerialConsole" ], - "operationId": "List_Operations", + "operationId": "ListOperations", "description": "Gets a list of Serial Console API operations.", - "x-ms-examples": { - "List all Serial Console management operations supported by Serial Console RP": { - "$ref": "./examples/GetOperationsExample.json" - } - }, "consumes": [ "application/json" ], @@ -55,9 +50,6 @@ "parameters": [ { "$ref": "#/parameters/ApiVersionParameter" - }, - { - "$ref": "#/parameters/SubscriptionIdParameter" } ], "responses": { @@ -67,16 +59,22 @@ "$ref": "#/definitions/SerialConsoleOperations" } } + }, + "x-ms-examples": { + "List all Serial Console management operations supported by Serial Console RP": { + "$ref": "./examples/GetOperationsExample.json" + } } } }, "/subscriptions/{subscriptionId}/providers/Microsoft.SerialConsole/consoleServices/{default}": { "get": { "tags": [ - "ConsoleDisabled" + "SerialConsole" ], - "operationId": "ListConsole_Disabled", - "description": "Gets if Serial Console is disabled for a subscription.", + "operationId": "GetConsoleStatus", + "summary": "Get the disabled status for a subscription", + "description": "Gets whether or not Serial Console is disabled for a given subscription", "parameters": [ { "$ref": "#/parameters/ApiVersionParameter" @@ -85,40 +83,38 @@ "$ref": "#/parameters/SubscriptionIdParameter" }, { - "$ref": "#/parameters/default" + "$ref": "#/parameters/defaultParameter" } ], "responses": { "200": { "description": "OK - Returns a JSON object", "schema": { - "$ref": "#/definitions/GetDisabledResult" + "$ref": "#/definitions/SerialConsoleStatus" } }, - "default": { - "description": "Error response describing why the operation failed.", + "404": { + "description": "Subscription not found - returns a JSON object with error details", "schema": { - "$ref": "#/definitions/DeploymentValidateResult" + "$ref": "#/definitions/GetSerialConsoleSubscriptionNotFound" } } }, "x-ms-examples": { - "Successfully get whether or not Serial Console is disabled": { - "$ref": "./examples/GetConsoleDisabledExamples.json" - }, - "Get whether or not Serial Console is disabled and receive error": { - "$ref": "./examples/GetConsoleDisabledExamples.json" + "Get the Serial Console disabled status for a subscription": { + "$ref": "./examples/SerialConsoleStatus.json" } } } }, - "/subscriptions/{subscriptionId}/providers/Microsoft.SerialConsole/consoleServices/{default}/enableConsole": { + "/subscriptions/{subscriptionId}/providers/Microsoft.SerialConsole/consoleServices/{default}/disableConsole": { "post": { "tags": [ - "EnableConsole" + "SerialConsole" ], - "operationId": "Console_EnableConsole", - "description": "Enables Serial Console for a subscription", + "operationId": "DisableConsole", + "summary": "Disable Serial Console for a subscription", + "description":"Disables the Serial Console service for all VMs and VM scale sets in the provided subscription", "parameters": [ { "$ref": "#/parameters/ApiVersionParameter" @@ -127,40 +123,38 @@ "$ref": "#/parameters/SubscriptionIdParameter" }, { - "$ref": "#/parameters/default" + "$ref": "#/parameters/defaultParameter" } ], "responses": { "200": { - "description": "OK - Serial Console disabled", + "description": "OK - Returns a JSON object", "schema": { - "$ref": "#/definitions/SetDisabledResult" + "$ref": "#/definitions/DisableSerialConsoleResult" } }, - "default": { - "description": "Error response describing why the operation failed.", + "404": { + "description": "Subscription not found - returns a JSON object with error details", "schema": { - "$ref": "#/definitions/DeploymentValidateResult" + "$ref": "#/definitions/GetSerialConsoleSubscriptionNotFound" } } }, "x-ms-examples": { - "Enable console successfully": { - "$ref": "./examples/EnableConsoleExamples.json" - }, - "Enable console with error": { - "$ref": "./examples/EnableConsoleExamples.json" + "Disable Serial Console for a subscription": { + "$ref": "./examples/DisableConsoleExamples.json" } } } }, - "/subscriptions/{subscriptionId}/providers/Microsoft.SerialConsole/consoleServices/{default}/disableConsole": { + "/subscriptions/{subscriptionId}/providers/Microsoft.SerialConsole/consoleServices/{default}/enableConsole": { "post": { "tags": [ - "DisableConsole" + "SerialConsole" ], - "operationId": "Console_DisableConsole", - "description": "Disables Serial Console for a subscription", + "operationId": "EnableConsole", + "summary": "Enable Serial Console for a subscription", + "description":"Enables the Serial Console service for all VMs and VM scale sets in the provided subscription", "parameters": [ { "$ref": "#/parameters/ApiVersionParameter" @@ -169,95 +163,121 @@ "$ref": "#/parameters/SubscriptionIdParameter" }, { - "$ref": "#/parameters/default" + "$ref": "#/parameters/defaultParameter" } ], "responses": { "200": { "description": "OK - Serial Console disabled", "schema": { - "$ref": "#/definitions/SetDisabledResult" + "$ref": "#/definitions/EnableSerialConsoleResult" } }, - "default": { - "description": "Error response describing why the operation failed.", + "404": { + "description": "Subscription not found - returns a JSON object with error details", "schema": { - "$ref": "#/definitions/DeploymentValidateResult" + "$ref": "#/definitions/GetSerialConsoleSubscriptionNotFound" } } }, "x-ms-examples": { - "Enable console successfully": { - "$ref": "./examples/DisableConsoleExamples.json" - }, - "Disable console with error": { - "$ref": "./examples/DisableConsoleExamples.json" + "Enable Serial Console for a subscription": { + "$ref": "./examples/EnableConsoleExamples.json" } } } } }, "definitions": { - "SerialConsoleGetResult": { + "SerialConsoleStatus": { "title": "Serial Console GET Result", "description": "Returns whether or not Serial Console is disabled.", + "type": "object", "properties": { - "value": { + "disabled": { "description": "Whether or not Serial Console is disabled.", "type": "boolean" } } }, - "GetDisabledResult": { - "title": "Get Disabled result", - "description": "Returns whether or not Serial Console is disabled for this given subscription", + "DisableSerialConsoleResult": { + "title": "Serial Console Disable Result", + "description": "Returns whether or not Serial Console is disabled.", + "type": "object", "properties": { "disabled": { - "description": "Disabled result", + "description": "Whether or not Serial Console is disabled.", "type": "boolean" } } }, - "SetDisabledResult": { - "title": "Set Disabled result", - "description": "Sets disable status and returns whether or not Serial Console is now disabled for this given subscription", + "EnableSerialConsoleResult": { + "title": "Serial Console Enable Result", + "description": "Returns whether or not Serial Console is disabled (enabled).", + "type": "object", "properties": { "disabled": { - "description": "Disabled result", + "description": "Whether or not Serial Console is disabled (enabled).", "type": "boolean" } } }, - "DeploymentValidateResult": { - "title": "Details on Failure", - "description": "Details on Failure", - "properties": { - "errorMessage": { - "description": "Error message", - "type": "string" - } - } - }, "SerialConsoleOperations": { "title": "Serial Console operations", "description": "Serial Console operations", "type": "object", "properties": { "value": { - "description": "Serial Console operations", + "description": "A list of Serial Console operations", + "type": "array", + "items": { + "type": "object", + "properties": { + "name": { + "type": "string" + }, + "isDataAction": { + "type": "string" + }, + "display": { + "type": "object", + "properties": { + "provider": { + "type": "string" + }, + "resource": { + "type": "string" + }, + "operation": { + "type": "string" + }, + "description": { + "type": "string" + } + } + } + } + } + } + } + }, + "GetSerialConsoleSubscriptionNotFound": { + "title": "Serial Console subscription not found", + "description": "Error saying that the provided subscription could not be found", + "type": "object", + "properties": { + "code": { + "description": "Error code", + "type": "string" + }, + "message": { + "description": "Subscription not found message", "type": "string" } } } }, "parameters": { - "SubscriptionIdParameter": { - "name": "subscriptionId", - "in": "path", - "required": true, - "type": "string", - "description": "The ID of the target subscription." - }, "ApiVersionParameter": { "name": "api-version", "in": "query", @@ -265,15 +285,19 @@ "type": "string", "description": "The API version to use for this operation." }, - "default": { + "SubscriptionIdParameter": { + "name": "subscriptionId", + "in": "path", + "required": true, + "type": "string", + "description": "Subscription ID which uniquely identifies the Microsoft Azure subscription. The subscription ID forms part of the URI for every service call requiring it." + }, + "defaultParameter": { "name": "default", "in": "path", "required": true, "type": "string", - "description": "Default string modeled as parameter for URL to work correctly.", - "enum": [ - "default" - ], + "description": "Default parameter. Leave the value as \"default\".", "x-ms-parameter-location": "method" } }