Skip to content

Commit

Permalink
fix(swagger): Modified XML comments for direct method APIs
Browse files Browse the repository at this point in the history
  • Loading branch information
@abhipsaMisra
abhipsaMisra committed May 7, 2020
1 parent e7dbe76 commit 6e70740
Showing 1 changed file with 16 additions and 9 deletions.
25 changes: 16 additions & 9 deletions sdk/iot/Azure.Iot.Hub.Service/src/swagger/iothubservice_modified_comments.json
View file
Original file line number Diff line number Diff line change
Expand Up @@ -1601,7 +1601,7 @@
"/twins/{deviceId}/methods": {
"post": {
"summary": "Invoke a direct method on a device.",
"description": "Invoke a direct method on a device. See https://docs.microsoft.com/azure/iot-hub/iot-hub-devguide-direct-methods for more information.",
"description": "Invoke a direct method on a device.",
"operationId": "DeviceMethod_InvokeDeviceMethod",
"consumes": [
"application/json"
Expand All @@ -1613,12 +1613,14 @@
{
"name": "deviceId",
"in": "path",
"description": "The ID of the device on which the direct method is to be invoked.",
"required": true,
"type": "string"
},
{
"name": "directMethodRequest",
"in": "body",
"description": "Parameters to execute a direct method on the device.",
"required": true,
"schema": {
"$ref": "#/definitions/CloudToDeviceMethod"
Expand All @@ -1630,7 +1632,7 @@
],
"responses": {
"200": {
"description": "Returns the method response payload",
"description": "Returns the direct method response payload.",
"schema": {
"$ref": "#/definitions/CloudToDeviceMethodResult"
}
Expand All @@ -1641,7 +1643,7 @@
"/twins/{deviceId}/modules/{moduleId}/methods": {
"post": {
"summary": "Invoke a direct method on a module of a device.",

This comment has been minimized.

Sign in to view

Copy link
@timtay-microsoft

timtay-microsoft May 8, 2020

Member

My PR goes into this as well, but these summary tags are pretty useless. The description tags are what get put in the method headers, whereas the summary tags aren't anywhere to be seen. I've been getting rid of the summary tags when they are just repeats of the description tag. Do you feel like this is a good idea to do here, too?

This comment has been minimized.

Sign in to view

Copy link
@abhipsaMisra

abhipsaMisra May 8, 2020

Author Member

Ah, I didn't notice that summary tags don't get reflected anywhere in our auto-gen code, thanks for pointing that out!
Yes, I will remove the summary tags from this PR as well.
"description": "Invoke a direct method on a module of a device. See https://docs.microsoft.com/azure/iot-hub/iot-hub-devguide-direct-methods for more information",
"description": "Invoke a direct method on a module of a device.",
"operationId": "DeviceMethod_InvokeModuleMethod",
"consumes": [
"application/json"
Expand All @@ -1653,18 +1655,21 @@
{
"name": "deviceId",
"in": "path",
"description": "The ID of the device on whose module the direct method is to be invoked.",

This comment has been minimized.

Sign in to view

Copy link
@timtay-microsoft

timtay-microsoft May 8, 2020

Member

nit: Id, not ID
"required": true,
"type": "string"
},
{
"name": "moduleId",
"in": "path",
"description": "The ID of the module on which the direct method is to be invoked.",
"required": true,
"type": "string"
},
{
"name": "directMethodRequest",
"in": "body",
"description": "Parameters to execute a direct method on the module.",
"required": true,
"schema": {
"$ref": "#/definitions/CloudToDeviceMethod"
Expand All @@ -1676,7 +1681,7 @@
],
"responses": {
"200": {
"description": "Returns the method response payload",
"description": "Returns the direct method response payload.",
"schema": {
"$ref": "#/definitions/CloudToDeviceMethodResult"
}
Expand Down Expand Up @@ -2820,22 +2825,24 @@
}
},
"CloudToDeviceMethod": {
"description": "Parameters to execute a direct method on the device",
"description": "Parameters to execute a direct method on the device.",
"type": "object",
"properties": {
"methodName": {
"description": "Method to run",
"description": "Name of the method which is to be executed.",
"type": "string"
},
"payload": {
"description": "Payload",
"description": "The JSON-formatted direct method payload, up to 128kb in size.",
"type": "object"
},
"responseTimeoutInSeconds": {
"description": "Timeout for the method invocation to return a response, defaults to 30 seconds. Minimum allowed value is 5 seconds, maximum allowed value is 300 seconds.",

This comment has been minimized.

Sign in to view

Copy link
@timtay-microsoft

timtay-microsoft May 8, 2020

Member

This parameter has always caused confusion with our customers. See this issue on our C# repo. Could you add some clarification that these parameters are only given to the service, not the device, and explain why that is?

This comment has been minimized.

Sign in to view

Copy link
@abhipsaMisra

abhipsaMisra May 8, 2020

Author Member

Sure thing, I can reword this and the description for connectTimeoutInSeconds as well, to reflect that service is the one who cares about/ acknowledges these values.
"format": "int32",
"type": "integer"
},
"connectTimeoutInSeconds": {
"description": "Timeout for the device to come online; defaults to 0, meaning the device must already be online. Maximum allowed value is 300 seconds.",
"format": "int32",
"type": "integer"
}
Expand Down Expand Up @@ -3038,11 +3045,11 @@
"properties": {
"status": {
"format": "int32",
"description": "Method invocation result status.",
"description": "Method invocation result status, provided by the device.",
"type": "integer"
},
"payload": {
"description": "Method invocation result payload.",
"description": "The JSON-formatted direct method result payload, up to 128kb in size; provided by the device.",
"type": "object"
}
}
Expand Down

0 comments on commit 6e70740

Please sign in to comment.