Updated the swagger content - Groups (#1211)

* Updated the swagger content for the APIs used to add devices to groups

* Formatting the swagger content
revert-70aa11f8
shavidissa 7 years ago committed by Madhawa Perera
parent 997bf0d16b
commit b9cde9b936

@ -67,7 +67,8 @@ import javax.ws.rs.core.Response;
}
)
@Path("/activities")
@Api(value = "Getting Activity Details", description = "Get the details of the operations/activities executed by the server on the registered devices during a defined time period.")
@Api(value = "Getting Activity Details", description = "Get the details of the operations/activities executed by the" +
" server on the registered devices during a defined time period.")
@Scopes(
scopes = {
@Scope(
@ -88,7 +89,8 @@ public interface ActivityInfoProviderService {
produces = MediaType.APPLICATION_JSON,
httpMethod = "GET",
value = "Getting the Details of a Specific Activity",
notes = "Retrieve the details of a specific activity/operation, such as the meta information of an operation, and the responses from the devices.",
notes = "Retrieve the details of a specific activity/operation, such as the meta information of an " +
"operation, and the responses from the devices.",
tags = "Activity Info Provider",
extensions = {
@Extension(properties = {
@ -160,7 +162,8 @@ public interface ActivityInfoProviderService {
produces = MediaType.APPLICATION_JSON,
httpMethod = "GET",
value = "Getting Activity Details of Specified Activity/Operation IDs",
notes = "Retrieve the details of activities or operations, such as the meta information of an operation, and the responses from the devices."+
notes = "Retrieve the details of activities or operations, such as the meta information of an operation," +
" and the responses from the devices."+
"Define the activity or operation IDs as comma separated values.",
tags = "Activity Info Provider",
extensions = {

@ -60,8 +60,8 @@ import javax.ws.rs.core.Response;
}
)
@Path("/configuration")
@Api(value = "Configuration Management", description = "The general platform configuration management capabilities are exposed " +
"through this API.")
@Api(value = "Configuration Management", description = "The general platform configuration management capabilities " +
"are exposed through this API.")
@Produces(MediaType.APPLICATION_JSON)
@Consumes(MediaType.APPLICATION_JSON)
@Scopes(scopes = {
@ -86,9 +86,9 @@ public interface ConfigurationManagementService {
produces = MediaType.APPLICATION_JSON,
httpMethod = "GET",
value = "Getting General Platform Configurations",
notes = "WSO2 EMM monitors policies to verify that the devices comply with the policies enforced on them. " +
"General platform configurations include the settings on how often the device need to be monitored. " +
"Using this REST API you can get the general platform level configurations.",
notes = "WSO2 EMM monitors policies to verify that the devices comply with the policies enforced on them." +
"General platform configurations include the settings on how often the device need to be " +
"monitored." + "Using this REST API you can get the general platform level configurations.",
tags = "Configuration Management",
extensions = {
@Extension(properties = {
@ -119,7 +119,8 @@ public interface ConfigurationManagementService {
),
@ApiResponse(
code = 304,
message = "Not Modified. \n Empty body because the client already has the latest version of the requested resource."),
message = "Not Modified. \n Empty body because the client already has the latest version of the " +
"requested resource."),
@ApiResponse(
code = 406,
message = "Not Acceptable.\n The requested media type is not supported."),
@ -146,8 +147,8 @@ public interface ConfigurationManagementService {
httpMethod = "PUT",
value = "Updating General Platform Configurations",
notes = "WSO2 EMM monitors policies to verify that the devices comply with the policies enforced on them." +
"General platform configurations include the settings on how often the the device need to be monitored." +
"Using this REST API you can update the general platform level configurations.",
"General platform configurations include the settings on how often the the device need to be " +
"monitored. Using this REST API you can update the general platform level configurations.",
tags = "Configuration Management",
extensions = {
@Extension(properties = {

@ -317,7 +317,8 @@ public interface DeviceAgentService {
consumes = MediaType.APPLICATION_JSON,
httpMethod = "POST",
value = "Publishing Events data only",
notes = "Publish events received by the device client to the WSO2 Data Analytics Server (DAS) using this API.",
notes = "Publish events received by the device client to the WSO2 Data Analytics Server (DAS) using this" +
" API.",
tags = "Device Agent Management",
extensions = {
@Extension(properties = {
@ -343,7 +344,8 @@ public interface DeviceAgentService {
}),
@ApiResponse(
code = 303,
message = "See Other. \n The source can be retrieved from the URL specified in the location header.",
message = "See Other. \n The source can be retrieved from the URL specified in the " +
"location header.",
responseHeaders = {
@ResponseHeader(
name = "Content-Location",
@ -353,7 +355,8 @@ public interface DeviceAgentService {
message = "Bad Request. \n Invalid request or validation error."),
@ApiResponse(
code = 415,
message = "Unsupported media type. \n The format of the requested entity was not supported."),
message = "Unsupported media type. \n The format of the requested entity was not " +
"supported."),
@ApiResponse(
code = 500,
message = "Internal Server Error. \n " +
@ -405,7 +408,8 @@ public interface DeviceAgentService {
"Used by caches, or in conditional requests."),
@ResponseHeader(
name = "Last-Modified",
description = "Date and time the resource has been modified the last time.\n" +
description = "Date and time the resource has been modified the last " +
"time.\n" +
"Used by caches, or in conditional requests."),
}),
@ApiResponse(
@ -438,7 +442,8 @@ public interface DeviceAgentService {
consumes = MediaType.APPLICATION_JSON,
httpMethod = "GET",
value = "Getting the Next Pending Operations of a Device",
notes = "There can be many operations that are pending on the device end. Get the next pending operation of a specific device using this API.",
notes = "There can be many operations that are pending on the device end. Get the next pending operation " +
"of a specific device using this API.",
tags = "Device Agent Management",
extensions = {
@Extension(properties = {
@ -483,7 +488,8 @@ public interface DeviceAgentService {
"Server error occurred while retrieving information requested device.",
response = ErrorResponse.class)
})
Response getNextPendingOperation(@ApiParam(name = "type", value = "The device type, such as ios, android, or windows.", required = true)
Response getNextPendingOperation(@ApiParam(name = "type", value = "The device type, such as ios, android, or " +
"windows.", required = true)
@PathParam("type") String type,
@ApiParam(name = "id", value = "The device ID.", required = true)
@PathParam("id") String deviceId);
@ -539,7 +545,8 @@ public interface DeviceAgentService {
"Server error occurred while retrieving information requested device.",
response = ErrorResponse.class)
})
Response updateOperation(@ApiParam(name = "type", value = "The device type, such as ios, android, or windows.", required = true)
Response updateOperation(@ApiParam(name = "type", value = "The device type, such as ios, android, or windows.",
required = true)
@PathParam("type") String type,
@ApiParam(name = "id", value = "The device ID.", required = true)
@PathParam("id") String deviceId,
@ -597,7 +604,8 @@ public interface DeviceAgentService {
"Server error occurred while retrieving information requested device.",
response = ErrorResponse.class)
})
Response updateDeviceProperties(@ApiParam(name = "type", value = "The device type, such as ios, android, or windows.", required = true)
Response updateDeviceProperties(@ApiParam(name = "type", value = "The device type, such as ios, android, or " +
"windows.", required = true)
@PathParam("type") String type,
@ApiParam(name = "id", value = "The device ID.", required = true)
@PathParam("id") String deviceId,
@ -611,7 +619,8 @@ public interface DeviceAgentService {
consumes = MediaType.APPLICATION_JSON,
httpMethod = "GET",
value = "Getting Specific Operations of a Device",
notes = "Device operations can be in the IN_PROGRESS, PENDING, COMPLETED, ERROR, or REPEATED status. You can use this API to get a list of all the operations that are in a specific status for a given device.",
notes = "Device operations can be in the IN_PROGRESS, PENDING, COMPLETED, ERROR, or REPEATED status. " +
"You can use this API to get a list of all the operations that are in a specific status for a given device.",
tags = "Device Agent Management",
extensions = {
@Extension(properties = {
@ -656,7 +665,8 @@ public interface DeviceAgentService {
"Server error occurred while retrieving information requested device.",
response = ErrorResponse.class)
})
Response getOperationsByDeviceAndStatus(@ApiParam(name = "type", value = "The device type, such as ios, android, or windows.", required = true)
Response getOperationsByDeviceAndStatus(@ApiParam(name = "type", value = "The device type, such as ios, android," +
" or windows.", required = true)
@PathParam("type") String type,
@ApiParam(name = "id", value = "The device ID.", required = true)
@PathParam("id") String deviceId,

@ -120,9 +120,11 @@ public interface DeviceEventManagementService {
response = ErrorResponse.class)
}
)
Response deployDeviceTypeEventDefinition(@ApiParam(name = "type", value = "The device type, such as android, ios, and windows.", required = false)
Response deployDeviceTypeEventDefinition(@ApiParam(name = "type", value = "The device type, such as android, ios," +
" and windows.", required = false)
@PathParam("type")String deviceType,
@ApiParam(name = "deviceTypeEvent", value = "Add the data to complete the DeviceTypeEvent object.", required = true)
@ApiParam(name = "deviceTypeEvent", value = "Add the data to complete " +
"the DeviceTypeEvent object.", required = true)
@Valid DeviceTypeEvent deviceTypeEvent);
@DELETE
@ -173,7 +175,8 @@ public interface DeviceEventManagementService {
response = ErrorResponse.class)
}
)
Response deleteDeviceTypeEventDefinitions(@ApiParam(name = "type", value = "The device type, such as android, ios, and windows.", required = false)
Response deleteDeviceTypeEventDefinitions(@ApiParam(name = "type", value = "The device type, such as android, " +
"ios, and windows.", required = false)
@PathParam("type")String deviceType);
@GET
@ -341,7 +344,8 @@ public interface DeviceEventManagementService {
response = ErrorResponse.class)
}
)
Response getDeviceTypeEventDefinition(@ApiParam(name = "type", value = "The type of the device, such as android, ios, or windows.", required = false)
Response getDeviceTypeEventDefinition(@ApiParam(name = "type", value = "The type of the device, such as android," +
" ios, or windows.", required = false)
@PathParam("type")String deviceType) ;
}

@ -549,7 +549,8 @@ public interface GeoLocationBasedService {
@PathParam("alertType") String alertType,
@ApiParam(
name = "queryName",
value = "When you define a geofence you define a fence name for it. That name needs to be defined here.",
value = "When you define a geofence you define a fence name for it. That name needs to be defined" +
" here.",
required = true)
@QueryParam("queryName") String queryName);
}

@ -72,8 +72,8 @@ import java.util.List;
),
tags = {
@Tag(name = "device_management", description = "Device group related REST-API. " +
"This can be used to manipulated device group related " +
"details.")
"This can be used to manipulated device group related " +
"details.")
}
)
@Scopes(
@ -166,7 +166,7 @@ import java.util.List;
)
@Path("/groups")
@Api(value = "Device Group Management", description = "This API carries all device group management related " +
"operations such as get all the available groups, etc.")
"operations such as get all the available groups, etc.")
@Produces(MediaType.APPLICATION_JSON)
@Consumes(MediaType.APPLICATION_JSON)
public interface GroupManagementService {
@ -179,9 +179,9 @@ public interface GroupManagementService {
notes = "Returns all groups enrolled with the system.",
tags = "Device Group Management",
extensions = {
@Extension(properties = {
@ExtensionProperty(name = Constants.SCOPE, value = "perm:groups:groups")
})
@Extension(properties = {
@ExtensionProperty(name = Constants.SCOPE, value = "perm:groups:groups")
})
}
)
@ApiResponses(value = {
@ -194,16 +194,16 @@ public interface GroupManagementService {
@ResponseHeader(
name = "ETag",
description = "Entity Tag of the response resource.\n" +
"Used by caches, or in conditional requests."),
"Used by caches, or in conditional requests."),
@ResponseHeader(
name = "Last-Modified",
description = "Date and time the resource has been modified the last time.\n" +
"Used by caches, or in conditional requests."),
"Used by caches, or in conditional requests."),
}),
@ApiResponse(
code = 304,
message = "Not Modified. \n Empty body because the client has already the latest version of " +
"the requested resource."),
"the requested resource."),
@ApiResponse(
code = 406,
message = "Not Acceptable.\n The requested media type is not supported."),
@ -213,8 +213,8 @@ public interface GroupManagementService {
response = ErrorResponse.class)
})
Response getGroups(@ApiParam(
name = "name",
value = "Name of the group.")
name = "name",
value = "Name of the group.")
@QueryParam("name")
String name,
@ApiParam(
@ -230,7 +230,8 @@ public interface GroupManagementService {
int offset,
@ApiParam(
name = "limit",
value = "Provide how many device details you require from the starting pagination index/offset.",
value = "Provide how many device details you require from the starting pagination " +
"index/offset.",
defaultValue = "5")
@QueryParam("limit")
int limit);
@ -244,9 +245,9 @@ public interface GroupManagementService {
notes = "Get the number of device groups in the server that the current signed in user can access.",
tags = "Device Group Management",
extensions = {
@Extension(properties = {
@ExtensionProperty(name = Constants.SCOPE, value = "perm:groups:count")
})
@Extension(properties = {
@ExtensionProperty(name = Constants.SCOPE, value = "perm:groups:count")
})
}
)
@ -260,16 +261,16 @@ public interface GroupManagementService {
@ResponseHeader(
name = "ETag",
description = "Entity Tag of the response resource.\n" +
"Used by caches, or in conditional requests."),
"Used by caches, or in conditional requests."),
@ResponseHeader(
name = "Last-Modified",
description = "Date and time the resource has been modified the last time.\n" +
"Used by caches, or in conditional requests."),
"Used by caches, or in conditional requests."),
}),
@ApiResponse(
code = 304,
message = "Not Modified. \n Empty body because the client has already the latest version of " +
"the requested resource."),
"the requested resource."),
@ApiResponse(
code = 406,
message = "Not Acceptable.\n The requested media type is not supported."),
@ -288,9 +289,9 @@ public interface GroupManagementService {
notes = "Add device group with the current user as the owner.",
tags = "Device Group Management",
extensions = {
@Extension(properties = {
@ExtensionProperty(name = Constants.SCOPE, value = "perm:groups:add")
})
@Extension(properties = {
@ExtensionProperty(name = Constants.SCOPE, value = "perm:groups:add")
})
}
)
@ApiResponses(
@ -308,16 +309,17 @@ public interface GroupManagementService {
@ResponseHeader(
name = "ETag",
description = "Entity Tag of the response resource.\n" +
"Used by caches, or in conditional requests."),
"Used by caches, or in conditional requests."),
@ResponseHeader(
name = "Last-Modified",
description = "Date and time the resource has been modified the last time.\n" +
"Used by caches, or in conditional requests.")
description = "Date and time the resource has been modified the last time" +
".\n" + "Used by caches, or in conditional requests.")
}
),
@ApiResponse(
code = 303,
message = "See Other. \n Source can be retrieved from the URL specified at the Location header.",
message = "See Other. \n Source can be retrieved from the URL specified at the Location " +
"header.",
responseHeaders = {
@ResponseHeader(
name = "Content-Location",
@ -332,17 +334,18 @@ public interface GroupManagementService {
response = ErrorResponse.class),
@ApiResponse(
code = 415,
message = "Unsupported media type. \n The entity of the request was in a not supported format."),
message = "Unsupported media type. \n The entity of the request was in a not supported " +
"format."),
@ApiResponse(
code = 500,
message = "Internal Server Error. \n " +
"Server error occurred while adding a new device group.",
"Server error occurred while adding a new device group.",
response = ErrorResponse.class)
})
Response createGroup(@ApiParam(
name = "group",
value = "Define the group object with data.",
required = true)
name = "group",
value = "Define the group object with data.",
required = true)
@Valid DeviceGroup group);
@Path("/id/{groupId}")
@ -354,9 +357,9 @@ public interface GroupManagementService {
notes = "Get the details of a specific device group.",
tags = "Device Group Management",
extensions = {
@Extension(properties = {
@ExtensionProperty(name = Constants.SCOPE, value = "perm:groups:groups-view")
})
@Extension(properties = {
@ExtensionProperty(name = Constants.SCOPE, value = "perm:groups:groups-view")
})
}
)
@ApiResponses(value = {
@ -369,16 +372,16 @@ public interface GroupManagementService {
@ResponseHeader(
name = "ETag",
description = "Entity Tag of the response resource.\n" +
"Used by caches, or in conditional requests."),
"Used by caches, or in conditional requests."),
@ResponseHeader(
name = "Last-Modified",
description = "Date and time the resource has been modified the last time.\n" +
"Used by caches, or in conditional requests."),
"Used by caches, or in conditional requests."),
}),
@ApiResponse(
code = 304,
message = "Not Modified. \n Empty body because the client has already the latest version of " +
"the requested resource."),
"the requested resource."),
@ApiResponse(
code = 404,
message = "Group found.",
@ -392,9 +395,9 @@ public interface GroupManagementService {
response = ErrorResponse.class)
})
Response getGroup(@ApiParam(
name = "groupId",
value = "The ID of the group.",
required = true)
name = "groupId",
value = "The ID of the group.",
required = true)
@PathParam("groupId") int groupId);
@Path("/id/{groupId}")
@ -406,9 +409,9 @@ public interface GroupManagementService {
notes = "If you wish to make changes to an existing group, that can be done by updating the group using this API",
tags = "Device Group Management",
extensions = {
@Extension(properties = {
@ExtensionProperty(name = Constants.SCOPE, value = "perm:groups:update")
})
@Extension(properties = {
@ExtensionProperty(name = Constants.SCOPE, value = "perm:groups:update")
})
}
)
@ApiResponses(value = {
@ -420,16 +423,16 @@ public interface GroupManagementService {
@ResponseHeader(
name = "ETag",
description = "Entity Tag of the response resource.\n" +
"Used by caches, or in conditional requests."),
"Used by caches, or in conditional requests."),
@ResponseHeader(
name = "Last-Modified",
description = "Date and time the resource has been modified the last time.\n" +
"Used by caches, or in conditional requests."),
"Used by caches, or in conditional requests."),
}),
@ApiResponse(
code = 304,
message = "Not Modified. \n Empty body because the client has already the latest version of " +
"the requested resource."),
"the requested resource."),
@ApiResponse(
code = 404,
message = "Group not found.",
@ -443,9 +446,9 @@ public interface GroupManagementService {
response = ErrorResponse.class)
})
Response updateGroup(@ApiParam(
name = "groupId",
value = "ID of the group to be updated.",
required = true)
name = "groupId",
value = "ID of the group to be updated.",
required = true)
@PathParam("groupId") int groupId,
@ApiParam(
name = "group",
@ -462,9 +465,9 @@ public interface GroupManagementService {
notes = "If you wish to remove an existing group, that can be done by updating the group using this API.",
tags = "Device Group Management",
extensions = {
@Extension(properties = {
@ExtensionProperty(name = Constants.SCOPE, value = "perm:groups:remove")
})
@Extension(properties = {
@ExtensionProperty(name = Constants.SCOPE, value = "perm:groups:remove")
})
}
)
@ApiResponses(value = {
@ -476,16 +479,16 @@ public interface GroupManagementService {
@ResponseHeader(
name = "ETag",
description = "Entity Tag of the response resource.\n" +
"Used by caches, or in conditional requests."),
"Used by caches, or in conditional requests."),
@ResponseHeader(
name = "Last-Modified",
description = "Date and time the resource has been modified the last time.\n" +
"Used by caches, or in conditional requests."),
"Used by caches, or in conditional requests."),
}),
@ApiResponse(
code = 304,
message = "Not Modified. \n Empty body because the client has already the latest version of " +
"the requested resource."),
"the requested resource."),
@ApiResponse(
code = 404,
message = "Group not found.",
@ -499,9 +502,9 @@ public interface GroupManagementService {
response = ErrorResponse.class)
})
Response deleteGroup(@ApiParam(
name = "groupId",
value = "ID of the group to be deleted.",
required = true)
name = "groupId",
value = "ID of the group to be deleted.",
required = true)
@PathParam("groupId") int groupId);
@Path("/id/{groupId}/share")
@ -510,12 +513,13 @@ public interface GroupManagementService {
produces = MediaType.APPLICATION_JSON,
httpMethod = HTTPConstants.HEADER_POST,
value = "Sharing a Group",
notes = "A device group can be shared with different user-roles. The users that belong to that role can then view the groups and the devices in it. Use this API to share a group among user roles.",
notes = "A device group can be shared with different user-roles. The users that belong to that role can " +
"then view the groups and the devices in it. Use this API to share a group among user roles.",
tags = "Device Group Management",
extensions = {
@Extension(properties = {
@ExtensionProperty(name = Constants.SCOPE, value = "perm:groups:share")
})
@Extension(properties = {
@ExtensionProperty(name = Constants.SCOPE, value = "perm:groups:share")
})
}
)
@ApiResponses(value = {
@ -527,16 +531,16 @@ public interface GroupManagementService {
@ResponseHeader(
name = "ETag",
description = "Entity Tag of the response resource.\n" +
"Used by caches, or in conditional requests."),
"Used by caches, or in conditional requests."),
@ResponseHeader(
name = "Last-Modified",
description = "Date and time the resource has been modified the last time.\n" +
"Used by caches, or in conditional requests."),
"Used by caches, or in conditional requests."),
}),
@ApiResponse(
code = 304,
message = "Not Modified. \n Empty body because the client has already the latest version of " +
"the requested resource."),
"the requested resource."),
@ApiResponse(
code = 404,
message = "Group not found.",
@ -550,9 +554,9 @@ public interface GroupManagementService {
response = ErrorResponse.class)
})
Response manageGroupSharing(@ApiParam(
name = "groupName",
value = "Name of the group to be shared or unshared.",
required = true)
name = "groupName",
value = "Name of the group to be shared or unshared.",
required = true)
@PathParam("groupId") int groupId,
@ApiParam(
name = "userRoles",
@ -566,12 +570,13 @@ public interface GroupManagementService {
produces = MediaType.APPLICATION_JSON,
httpMethod = HTTPConstants.HEADER_GET,
value = "Getting the List of Roles the Group is Shared With",
notes = "A device group can be shared with different user-roles. The users that belong to that role can then view the groups and the devices in it. Using this API you get the list of roles the device group is shared with.",
notes = "A device group can be shared with different user-roles. The users that belong to that role can" +
"then view the groups and the devices in it. Using this API you get the list of roles the device group is shared with.",
tags = "Device Group Management",
extensions = {
@Extension(properties = {
@ExtensionProperty(name = Constants.SCOPE, value = "perm:groups:roles")
})
@Extension(properties = {
@ExtensionProperty(name = Constants.SCOPE, value = "perm:groups:roles")
})
}
)
@ApiResponses(value = {
@ -607,9 +612,9 @@ public interface GroupManagementService {
response = ErrorResponse.class)
})
Response getRolesOfGroup(@ApiParam(
name = "groupId",
value = "ID of the group.",
required = true)
name = "groupId",
value = "ID of the group.",
required = true)
@PathParam("groupId") int groupId);
@Path("/id/{groupId}/devices")
@ -621,9 +626,9 @@ public interface GroupManagementService {
notes = "Returns the list of devices in a device group.",
tags = "Device Group Management",
extensions = {
@Extension(properties = {
@ExtensionProperty(name = Constants.SCOPE, value = "perm:groups:devices")
})
@Extension(properties = {
@ExtensionProperty(name = Constants.SCOPE, value = "perm:groups:devices")
})
}
)
@ApiResponses(value = {
@ -636,16 +641,16 @@ public interface GroupManagementService {
@ResponseHeader(
name = "ETag",
description = "Entity Tag of the response resource.\n" +
"Used by caches, or in conditional requests."),
"Used by caches, or in conditional requests."),
@ResponseHeader(
name = "Last-Modified",
description = "Date and time the resource has been modified the last time.\n" +
"Used by caches, or in conditional requests."),
"Used by caches, or in conditional requests."),
}),
@ApiResponse(
code = 304,
message = "Not Modified. \n Empty body because the client has already the latest version of " +
"the requested resource."),
"the requested resource."),
@ApiResponse(
code = 404,
message = "Group not found.",
@ -659,9 +664,9 @@ public interface GroupManagementService {
response = ErrorResponse.class)
})
Response getDevicesOfGroup(@ApiParam(
name = "groupId",
value = "ID of the group.",
required = true)
name = "groupId",
value = "ID of the group.",
required = true)
@PathParam("groupId")
int groupId,
@ApiParam(
@ -672,7 +677,8 @@ public interface GroupManagementService {
int offset,
@ApiParam(
name = "limit",
value = "Provide how many group details you require from the starting pagination index/offset.",
value = "Provide how many group details you require from the starting " +
"pagination index/offset.",
defaultValue = "5")
@QueryParam("limit")
int limit);
@ -686,9 +692,9 @@ public interface GroupManagementService {
notes = "Get the number of devices in a group using this API.",
tags = "Device Group Management",
extensions = {
@Extension(properties = {
@ExtensionProperty(name = Constants.SCOPE, value = "perm:groups:devices-count")
})
@Extension(properties = {
@ExtensionProperty(name = Constants.SCOPE, value = "perm:groups:devices-count")
})
}
)
@ApiResponses(value = {
@ -701,16 +707,16 @@ public interface GroupManagementService {
@ResponseHeader(
name = "ETag",
description = "Entity Tag of the response resource.\n" +
"Used by caches, or in conditional requests."),
"Used by caches, or in conditional requests."),
@ResponseHeader(
name = "Last-Modified",
description = "Date and time the resource has been modified the last time.\n" +
"Used by caches, or in conditional requests."),
"Used by caches, or in conditional requests."),
}),
@ApiResponse(
code = 304,
message = "Not Modified. \n Empty body because the client has already the latest version of " +
"the requested resource."),
"the requested resource."),
@ApiResponse(
code = 404,
message = "No groups found.",
@ -724,23 +730,23 @@ public interface GroupManagementService {
response = ErrorResponse.class)
})
Response getDeviceCountOfGroup(@ApiParam(
name = "groupId",
value = "ID of the group.",
required = true)
@PathParam("groupId") int groupId);
name = "groupId",
value = "ID of the group.",
required = true)
@PathParam("groupId") int groupId);
@Path("/id/{groupId}/devices/add")
@POST
@ApiOperation(
produces = MediaType.APPLICATION_JSON,
httpMethod = HTTPConstants.HEADER_POST,
value = "Adding Devices to Group",
value = "Adding Devices to a Group",
notes = "Add the enrolled devices to a group.",
tags = "Device Group Management",
extensions = {
@Extension(properties = {
@ExtensionProperty(name = Constants.SCOPE, value = "perm:groups:devices-add")
})
@Extension(properties = {
@ExtensionProperty(name = Constants.SCOPE, value = "perm:groups:devices-add")
})
}
)
@ApiResponses(value = {
@ -752,16 +758,16 @@ public interface GroupManagementService {
@ResponseHeader(
name = "ETag",
description = "Entity Tag of the response resource.\n" +
"Used by caches, or in conditional requests."),
"Used by caches, or in conditional requests."),
@ResponseHeader(
name = "Last-Modified",
description = "Date and time the resource has been modified the last time.\n" +
"Used by caches, or in conditional requests."),
"Used by caches, or in conditional requests."),
}),
@ApiResponse(
code = 304,
message = "Not Modified. \n Empty body because the client has already the latest version of " +
"the requested resource."),
"the requested resource."),
@ApiResponse(
code = 404,
message = "No groups found.",
@ -775,9 +781,9 @@ public interface GroupManagementService {
response = ErrorResponse.class)
})
Response addDevicesToGroup(@ApiParam(
name = "groupId",
value = "ID of the group.",
required = true)
name = "groupId",
value = "ID of the group.",
required = true)
@PathParam("groupId") int groupId,
@ApiParam(
name = "deviceIdentifiers",
@ -794,9 +800,9 @@ public interface GroupManagementService {
notes = "Remove a device from a group using this API.",
tags = "Device Group Management",
extensions = {
@Extension(properties = {
@ExtensionProperty(name = Constants.SCOPE, value = "perm:groups:devices-remove")
})
@Extension(properties = {
@ExtensionProperty(name = Constants.SCOPE, value = "perm:groups:devices-remove")
})
}
)
@ApiResponses(value = {
@ -808,16 +814,16 @@ public interface GroupManagementService {
@ResponseHeader(
name = "ETag",
description = "Entity Tag of the response resource.\n" +
"Used by caches, or in conditional requests."),
"Used by caches, or in conditional requests."),
@ResponseHeader(
name = "Last-Modified",
description = "Date and time the resource has been modified the last time.\n" +
"Used by caches, or in conditional requests."),
"Used by caches, or in conditional requests."),
}),
@ApiResponse(
code = 304,
message = "Not Modified. \n Empty body because the client has already the latest version of " +
"the requested resource."),
"the requested resource."),
@ApiResponse(
code = 404,
message = "No groups found.",
@ -831,13 +837,14 @@ public interface GroupManagementService {
response = ErrorResponse.class)
})
Response removeDevicesFromGroup(@ApiParam(
name = "groupId",
value = "ID of the group.",
required = true)
name = "groupId",
value = "ID of the group.",
required = true)
@PathParam("groupId") int groupId,
@ApiParam(
name = "deviceIdentifiers",
value = "The device identifiers of the devices that needed to be removed. You can define many device IDs as comma separated values.",
value = "The device identifiers of the devices that needed to be removed."+
" You can define many device IDs as comma separated values.",
required = true)
@Valid List<DeviceIdentifier> deviceIdentifiers);
@ -846,8 +853,8 @@ public interface GroupManagementService {
@ApiOperation(
produces = MediaType.APPLICATION_JSON,
httpMethod = HTTPConstants.HEADER_POST,
value = "Adding Devices to a Group",
notes = "Add the existing devices to a device groups.",
value = "Adding a Device to Many Groups",
notes = "Add an already enrolled device to many groups, using this API.",
tags = "Device Group Management",
extensions = {
@Extension(properties = {
@ -864,16 +871,16 @@ public interface GroupManagementService {
@ResponseHeader(
name = "ETag",
description = "Entity Tag of the response resource.\n" +
"Used by caches, or in conditional requests."),
"Used by caches, or in conditional requests."),
@ResponseHeader(
name = "Last-Modified",
description = "Date and time the resource has been modified the last time.\n" +
"Used by caches, or in conditional requests."),
"Used by caches, or in conditional requests."),
}),
@ApiResponse(
code = 304,
message = "Not Modified. \n Empty body because the client has already the latest version of " +
"the requested resource."),
"the requested resource."),
@ApiResponse(
code = 404,
message = "No groups found.",
@ -889,7 +896,9 @@ public interface GroupManagementService {
Response updateDeviceAssigningToGroups(
@ApiParam(
name = "deviceToGroupsAssignment",
value = "Define the group ID and the device identifiers of the devices that need to be added to the group in the payload.",
value = "In the payload, define the group IDs that you need to add the device to as comma " +
"separated values, and the device identifier and type of the device, such as android, " +
"ios, and windows, that needs to be added to the groups.",
required = true)
@Valid DeviceToGroupsAssignment deviceToGroupsAssignment);
@ -899,7 +908,8 @@ public interface GroupManagementService {
produces = MediaType.APPLICATION_JSON,
httpMethod = HTTPConstants.HEADER_GET,
value = "Getting Device Groups that Include the Specific Device",
notes = " device can be added to one or many groups. This API gives you the list of groups the device has been added to.",
notes = " device can be added to one or many groups. This API gives you the list of groups the device " +
"has been added to.",
tags = "Device Group Management",
extensions = {
@Extension(properties = {
@ -916,16 +926,16 @@ public interface GroupManagementService {
@ResponseHeader(
name = "ETag",
description = "Entity Tag of the response resource.\n" +
"Used by caches, or in conditional requests."),
"Used by caches, or in conditional requests."),
@ResponseHeader(
name = "Last-Modified",
description = "Date and time the resource has been modified the last time.\n" +
"Used by caches, or in conditional requests."),
"Used by caches, or in conditional requests."),
}),
@ApiResponse(
code = 304,
message = "Not Modified. \n Empty body because the client has already the latest version of " +
"the requested resource."),
"the requested resource."),
@ApiResponse(
code = 406,
message = "Not Acceptable.\n The requested media type is not supported."),

@ -136,7 +136,8 @@ import java.util.List;
)
}
)
@Api(value = "Device Policy Management", description = "This API includes the functionality around device policy management")
@Api(value = "Device Policy Management", description = "This API includes the functionality around device policy " +
"management")
@Path("/policies")
@Produces(MediaType.APPLICATION_JSON)
@Consumes(MediaType.APPLICATION_JSON)
@ -148,8 +149,10 @@ public interface PolicyManagementService {
produces = MediaType.APPLICATION_JSON,
httpMethod = "POST",
value = "Adding a Policy",
notes = "Add a policy using this REST API command. When adding a policy you will have the option of saving the policy or saving and publishing the policy." +
"Using this REST API you are able to save a created Policy and this policy will be in the inactive state.",
notes = "Add a policy using this REST API command. When adding a policy you will have the option of " +
"saving the policy or saving and publishing the policy." +
"Using this REST API you are able to save a created Policy and this policy will be in the " +
"inactive state.",
tags = "Device Policy Management",
extensions = {
@Extension(properties = {
@ -181,7 +184,8 @@ public interface PolicyManagementService {
),
@ApiResponse(
code = 303,
message = "See Other. \n The source can be retrieved from the URL specified in the location header",
message = "See Other. \n The source can be retrieved from the URL specified in the " +
"location header",
responseHeaders = {
@ResponseHeader(
name = "Content-Location",
@ -192,11 +196,13 @@ public interface PolicyManagementService {
response = ErrorResponse.class),
@ApiResponse(
code = 401,
message = "Not Found. \n The user that is currently logged in is not authorized to add policies.",
message = "Not Found. \n The user that is currently logged in is not authorized to add " +
"policies.",
response = ErrorResponse.class),
@ApiResponse(
code = 415,
message = "Unsupported media type. \n The format of the requested entity was not supported."),
message = "Unsupported media type. \n The format of the requested entity was not " +
"supported."),
@ApiResponse(
code = 500,
message = "Internal Server Error. \n " +
@ -248,7 +254,8 @@ public interface PolicyManagementService {
),
@ApiResponse(
code = 304,
message = "Not Modified. \n Empty body because the client already has the latest version of the requested resource."),
message = "Not Modified. \n Empty body because the client already has the latest version " +
"of the requested resource."),
@ApiResponse(
code = 400,
message = "Bad Request. \n Invalid request or validation error.",
@ -322,7 +329,8 @@ public interface PolicyManagementService {
),
@ApiResponse(
code = 304,
message = "Not Modified. \n Empty body because the client already has the latest version of the requested resource.\n"),
message = "Not Modified. \n Empty body because the client already has the latest version " +
"of the requested resource.\n"),
@ApiResponse(
code = 404,
message = "Not Found. \n A specified policy was not found.",
@ -400,7 +408,8 @@ public interface PolicyManagementService {
response = ErrorResponse.class),
@ApiResponse(
code = 415,
message = "Unsupported media type. \n The format of the requested entity was not supported."),
message = "Unsupported media type. \n The format of the requested entity was not " +
"supported."),
@ApiResponse(
code = 500,
message = "Internal Server Error. \n " +
@ -451,7 +460,8 @@ public interface PolicyManagementService {
response = ErrorResponse.class),
@ApiResponse(
code = 415,
message = "Unsupported media type. \n The format of the requested entity was not supported.\n "
message = "Unsupported media type. \n The format of the requested entity was not " +
"supported.\n "
+ "supported format."),
@ApiResponse(
code = 500,
@ -474,7 +484,8 @@ public interface PolicyManagementService {
produces = MediaType.APPLICATION_JSON,
httpMethod = "POST",
value = "Activating Policies",
notes = "Publish a policy using this API to bring a policy that is in the inactive state to the active state.",
notes = "Publish a policy using this API to bring a policy that is in the inactive state to the active " +
"state.",
tags = "Device Policy Management",
extensions = {
@Extension(properties = {
@ -515,7 +526,8 @@ public interface PolicyManagementService {
produces = MediaType.APPLICATION_JSON,
httpMethod = "POST",
value = "Deactivating Policies",
notes = "Unpublish a policy using this API to bring a policy that is in the active state to the inactive state.",
notes = "Unpublish a policy using this API to bring a policy that is in the active state to the inactive " +
"state.",
tags = "Device Policy Management",
extensions = {
@Extension(properties = {
@ -655,7 +667,8 @@ public interface PolicyManagementService {
),
@ApiResponse(
code = 304,
message = "Not Modified. \n Empty body because the client already has the latest version of the requested resource.\n"),
message = "Not Modified. \n Empty body because the client already has the latest version " +
"of the requested resource.\n"),
@ApiResponse(
code = 404,
message = "Not Found. \n A specified policy was not found.",

@ -482,7 +482,9 @@ public interface RoleManagementService {
produces = MediaType.APPLICATION_JSON,
httpMethod = "POST",
value = "Adding a combined Role",
notes = "You are able to combine two roles that already exist and create one role. For example, you might want a role that has device owner and application management role permissions, you can now select these two roles and create another new role that has all their permissions.",
notes = "You are able to combine two roles that already exist and create one role. For example, you " +
"might want a role that has device owner and application management role permissions, you can" +
" now select these two roles and create another new role that has all their permissions.",
tags = "Role Management",
extensions = {
@Extension(properties = {
@ -511,7 +513,8 @@ public interface RoleManagementService {
"Used by caches, or in conditional requests.")}),
@ApiResponse(
code = 303,
message = "See Other. \n The source can be retrieved from the URL specified in the location header.",
message = "See Other. \n The source can be retrieved from the URL specified in the location " +
"header.",
responseHeaders = {
@ResponseHeader(
name = "Content-Location",
@ -597,7 +600,8 @@ public interface RoleManagementService {
name = "role",
value = "The properties required to update a role.\n" +
"NOTE: Don't change the role and the permissions of the admin user. " +
"If you want to try out this API by updating all the properties, create a new role and update the properties accordingly.",
"If you want to try out this API by updating all the properties, create a new role " +
"and update the properties accordingly.",
required = true) RoleInfo role,
@ApiParam(
name = "user-store",
@ -610,7 +614,8 @@ public interface RoleManagementService {
@ApiOperation(
httpMethod = "DELETE",
value = "Deleting a Role",
notes = "Roles become obsolete over time due to various reasons. In a situation where your Organization identifies that a specific role is no longer required, you " +
notes = "Roles become obsolete over time due to various reasons. In a situation where your " +
"Organization identifies that a specific role is no longer required, you " +
"can delete a role using this REST API.",
tags = "Role Management",
extensions = {
@ -659,8 +664,10 @@ public interface RoleManagementService {
notes = "Defining users to a role at the point of creating a new role is optional. " +
"You can update the users that belong to a given role after you have created " +
"a role using this REST API.\n" +
"Example: Your Organization hires 30 new engineers. Updating the role details for each user can " +
"be cumbersome. Therefore, you can define all the new employees that belong to the engineering " +
"Example: Your Organization hires 30 new engineers. Updating the role details for each user " +
"can " +
"be cumbersome. Therefore, you can define all the new employees that belong to the " +
"engineering " +
"role using this API.",
tags = "Role Management",
extensions = {
@ -684,7 +691,8 @@ public interface RoleManagementService {
"Used by caches, or in conditional requests."),
@ResponseHeader(
name = "Last-Modified",
description = "Date and time the resource has been modified the last time.\n" +
description = "Date and time the resource has been modified the last " +
"time.\n" +
"Used by caches, or in conditional requests.")}),
@ApiResponse(
code = 400,
@ -696,7 +704,8 @@ public interface RoleManagementService {
response = ErrorResponse.class),
@ApiResponse(
code = 415,
message = "Unsupported media type. \n The format of the requested entity was not supported.\n" +
message = "Unsupported media type. \n The format of the requested entity was not " +
"supported.\n" +
"supported format.",
response = ErrorResponse.class),
@ApiResponse(

@ -155,7 +155,8 @@ public interface UserManagementService {
produces = MediaType.APPLICATION_JSON,
httpMethod = "POST",
value = "Adding a User",
notes = "WSO2 IoTS supports user management. Add a new user to the WSO2 IoTS user management system via this REST API",
notes = "WSO2 IoTS supports user management. Add a new user to the WSO2 IoTS user management system via " +
"this REST API",
tags = "User Management",
extensions = {
@Extension(properties = {
@ -243,7 +244,8 @@ public interface UserManagementService {
}),
@ApiResponse(
code = 304,
message = "Not Modified. \n Empty body because the client already has the latest version of the requested resource."),
message = "Not Modified. \n Empty body because the client already has the latest version of the " +
"requested resource."),
@ApiResponse(
code = 404,
message = "Not Found. \n The specified resource does not exist.",
@ -351,7 +353,8 @@ public interface UserManagementService {
@ApiOperation(
httpMethod = "DELETE",
value = "Deleting a User",
notes = "When an employee leaves the organization, you can remove the user details from WSO2 IoTS using this REST API.",
notes = "When an employee leaves the organization, you can remove the user details from WSO2 IoTS using " +
"this REST API.",
tags = "User Management",
extensions = {
@Extension(properties = {
@ -378,7 +381,8 @@ public interface UserManagementService {
@ApiParam(
name = "username",
value = "Username of the user to be deleted.\n" +
"INFO: If you want to try out this API, make sure to create a new user and then remove that user. Do not remove the admin user.",
"INFO: If you want to try out this API, make sure to create a new user and then remove " +
"that user. Do not remove the admin user.",
required = true,
defaultValue = "[Create a new user named Jim, and then try out this API.]")
@PathParam("username") String username,
@ -394,7 +398,8 @@ public interface UserManagementService {
produces = MediaType.APPLICATION_JSON,
httpMethod = "GET",
value = "Getting the Role Details of a User",
notes = "A user can be assigned to one or more role in IoTS. Using this REST API you can get the role/roles a user is assigned to.",
notes = "A user can be assigned to one or more role in IoTS. Using this REST API you can get the " +
"role/roles a user is assigned to.",
tags = "User Management",
extensions = {
@Extension(properties = {
@ -422,7 +427,8 @@ public interface UserManagementService {
}),
@ApiResponse(
code = 304,
message = "Not Modified. \n Empty body because the client already has the latest version of the requested resource."),
message = "Not Modified. \n Empty body because the client already has the latest version of the " +
"requested resource."),
@ApiResponse(
code = 404,
message = "Not Found. \n The specified resource does not exist.\n",
@ -455,7 +461,8 @@ public interface UserManagementService {
produces = MediaType.APPLICATION_JSON,
httpMethod = "GET",
value = "Getting Details of Users",
notes = "You are able to manage users in WSO2 IoTS by adding, updating and removing users. If you wish to get the list of users registered with WSO2 IoTS, you can do so "
notes = "You are able to manage users in WSO2 IoTS by adding, updating and removing users. If you wish to" +
" get the list of users registered with WSO2 IoTS, you can do so "
+ "using this REST API",
tags = "User Management",
extensions = {
@ -492,7 +499,8 @@ public interface UserManagementService {
response = ErrorResponse.class),
@ApiResponse(
code = 500,
message = "Internal Server Error. \n Server error occurred while fetching the list of WSO2 IoTS users.",
message = "Internal Server Error. \n Server error occurred while fetching the list of WSO2 IoTS " +
"users.",
response = ErrorResponse.class)
})
Response getUsers(
@ -551,7 +559,8 @@ public interface UserManagementService {
response = ErrorResponse.class),
@ApiResponse(
code = 500,
message = "Internal Server Error. \n Server error occurred while fetching the total number of users in WSO2 IoTS.",
message = "Internal Server Error. \n Server error occurred while fetching the total number of " +
"users in WSO2 IoTS.",
response = ErrorResponse.class)
})
Response getUserCount();
@ -602,7 +611,8 @@ public interface UserManagementService {
produces = MediaType.APPLICATION_JSON,
httpMethod = "GET",
value = "Searching for a User Name",
notes = "If you are unsure of the user name of a user and need to retrieve the details of a specific user, you can "
notes = "If you are unsure of the user name of a user and need to retrieve the details of a specific " +
"user, you can "
+ "search for that user by giving a character or a few characters in the username. "
+ "You will be given a list of users having the user name in the exact order of the "
+ "characters you provided.",
@ -634,14 +644,16 @@ public interface UserManagementService {
}),
@ApiResponse(
code = 304,
message = "Not Modified. \n Empty body because the client already has the latest version of the requested resource."),
message = "Not Modified. \n Empty body because the client already has the latest version of the " +
"requested resource."),
@ApiResponse(
code = 406,
message = "Not Acceptable.\n The requested media type is not supported",
response = ErrorResponse.class),
@ApiResponse(
code = 500,
message = "Internal Server Error. \n Server error occurred while fetching the list of users that matched the given filter.",
message = "Internal Server Error. \n Server error occurred while fetching the list of users that " +
"matched the given filter.",
response = ErrorResponse.class)
})
Response getUserNames(
@ -727,7 +739,9 @@ public interface UserManagementService {
httpMethod = "POST",
value = "Sending Enrollment Invitations to Users",
notes = "Send the users a mail inviting them to enroll their devices using the REST API given below.\n" +
"Before running the REST API command to send the enrollment invitations to users make sure to configure WSO2 IoTS as explained in step 4, under the WSO2 IoTS general server configurations documentation.",
"Before running the REST API command to send the enrollment invitations to users make sure to " +
"configure WSO2 IoTS as explained in step 4, under the WSO2 IoTS general server configurations " +
"documentation.",
tags = "User Management",
extensions = {
@Extension(properties = {

Loading…
Cancel
Save