From 0cf0ec6e77b4ac55706fb395374e34bc20e35e2a Mon Sep 17 00:00:00 2001 From: inosh-perera Date: Fri, 13 May 2016 01:30:17 +0530 Subject: [PATCH] adding swagger annotations to APIs --- .../device/mgt/jaxrs/api/Certificate.java | 3 ++- .../device/mgt/jaxrs/api/Configuration.java | 4 ++- .../carbon/device/mgt/jaxrs/api/Device.java | 3 ++- .../mgt/jaxrs/api/DeviceInformation.java | 3 ++- .../mgt/jaxrs/api/DeviceNotification.java | 2 +- .../device/mgt/jaxrs/api/DeviceSearch.java | 3 ++- .../carbon/device/mgt/jaxrs/api/Feature.java | 3 ++- .../device/mgt/jaxrs/api/Operation.java | 3 ++- .../carbon/device/mgt/jaxrs/api/Policy.java | 3 ++- .../carbon/device/mgt/jaxrs/api/Role.java | 2 +- .../carbon/device/mgt/jaxrs/api/User.java | 2 +- .../mgt/jaxrs/beans/ApplicationWrapper.java | 9 +++++++ .../jaxrs/beans/EnrollmentCertificate.java | 10 +++++++ .../device/mgt/jaxrs/beans/MobileApp.java | 27 +++++++++++++++++++ .../jaxrs/beans/UserCredentialWrapper.java | 7 +++++ .../device/mgt/jaxrs/beans/UserWrapper.java | 10 +++++++ .../common/notification/mgt/Notification.java | 14 ++++++++++ 17 files changed, 97 insertions(+), 11 deletions(-) diff --git a/components/device-mgt/org.wso2.carbon.device.mgt.api/src/main/java/org/wso2/carbon/device/mgt/jaxrs/api/Certificate.java b/components/device-mgt/org.wso2.carbon.device.mgt.api/src/main/java/org/wso2/carbon/device/mgt/jaxrs/api/Certificate.java index 962603e262..af03e226aa 100644 --- a/components/device-mgt/org.wso2.carbon.device.mgt.api/src/main/java/org/wso2/carbon/device/mgt/jaxrs/api/Certificate.java +++ b/components/device-mgt/org.wso2.carbon.device.mgt.api/src/main/java/org/wso2/carbon/device/mgt/jaxrs/api/Certificate.java @@ -36,7 +36,8 @@ import javax.ws.rs.core.Response; /** * All the certificate related tasks such as saving certificates, can be done through this endpoint. */ -@Api(value = "Certificate", description = "Certificate related tasks such as saving certificates") +@Api(value = "Certificate", description = "Certificate related tasks such as saving certificates, " + + "can be done through this API") @SuppressWarnings("NonJaxWsWebServices") @Produces({ "application/json", "application/xml" }) @Consumes({ "application/json", "application/xml" }) diff --git a/components/device-mgt/org.wso2.carbon.device.mgt.api/src/main/java/org/wso2/carbon/device/mgt/jaxrs/api/Configuration.java b/components/device-mgt/org.wso2.carbon.device.mgt.api/src/main/java/org/wso2/carbon/device/mgt/jaxrs/api/Configuration.java index 12e21f451b..7c5db4f189 100644 --- a/components/device-mgt/org.wso2.carbon.device.mgt.api/src/main/java/org/wso2/carbon/device/mgt/jaxrs/api/Configuration.java +++ b/components/device-mgt/org.wso2.carbon.device.mgt.api/src/main/java/org/wso2/carbon/device/mgt/jaxrs/api/Configuration.java @@ -34,7 +34,9 @@ import javax.ws.rs.core.Response; * General Tenant Configuration REST-API implementation. * All end points support JSON, XMl with content negotiation. */ -@Api(value = "Configuration", description = "General Tenant Configuration implementation") +@Api(value = "Configuration", description = "General Tenant Configuration management capabilities are exposed " + + "through " + + "this API") @SuppressWarnings("NonJaxWsWebServices") @Produces({ "application/json", "application/xml" }) @Consumes({ "application/json", "application/xml" }) diff --git a/components/device-mgt/org.wso2.carbon.device.mgt.api/src/main/java/org/wso2/carbon/device/mgt/jaxrs/api/Device.java b/components/device-mgt/org.wso2.carbon.device.mgt.api/src/main/java/org/wso2/carbon/device/mgt/jaxrs/api/Device.java index 9710e6f426..0dc381d335 100644 --- a/components/device-mgt/org.wso2.carbon.device.mgt.api/src/main/java/org/wso2/carbon/device/mgt/jaxrs/api/Device.java +++ b/components/device-mgt/org.wso2.carbon.device.mgt.api/src/main/java/org/wso2/carbon/device/mgt/jaxrs/api/Device.java @@ -29,7 +29,8 @@ import javax.ws.rs.core.Response; /** * Device related operations such as get all the available devices, etc. */ -@Api(value = "Devices") + +@Api(value = "Device", description = "Device related operations such as get all the available devices, etc.") @SuppressWarnings("NonJaxWsWebServices") public interface Device { diff --git a/components/device-mgt/org.wso2.carbon.device.mgt.api/src/main/java/org/wso2/carbon/device/mgt/jaxrs/api/DeviceInformation.java b/components/device-mgt/org.wso2.carbon.device.mgt.api/src/main/java/org/wso2/carbon/device/mgt/jaxrs/api/DeviceInformation.java index d55477eb07..40bd74aa62 100644 --- a/components/device-mgt/org.wso2.carbon.device.mgt.api/src/main/java/org/wso2/carbon/device/mgt/jaxrs/api/DeviceInformation.java +++ b/components/device-mgt/org.wso2.carbon.device.mgt.api/src/main/java/org/wso2/carbon/device/mgt/jaxrs/api/DeviceInformation.java @@ -36,7 +36,8 @@ import javax.ws.rs.core.Response; /** * Device information related operations. */ -@Api(value = "DeviceInfo") + +@Api(value = "DeviceInformation", description = "Device information related operations can be found here.") @SuppressWarnings("NonJaxWsWebServices") public interface DeviceInformation { diff --git a/components/device-mgt/org.wso2.carbon.device.mgt.api/src/main/java/org/wso2/carbon/device/mgt/jaxrs/api/DeviceNotification.java b/components/device-mgt/org.wso2.carbon.device.mgt.api/src/main/java/org/wso2/carbon/device/mgt/jaxrs/api/DeviceNotification.java index e01110ff77..41f1747b34 100644 --- a/components/device-mgt/org.wso2.carbon.device.mgt.api/src/main/java/org/wso2/carbon/device/mgt/jaxrs/api/DeviceNotification.java +++ b/components/device-mgt/org.wso2.carbon.device.mgt.api/src/main/java/org/wso2/carbon/device/mgt/jaxrs/api/DeviceNotification.java @@ -40,7 +40,7 @@ import javax.ws.rs.core.Response; * DeviceNotification management REST-API implementation. * All end points support JSON, XMl with content negotiation. */ -@Api(value = "DeviceNotification") +@Api(value = "DeviceNotification", description = "Device notification related operations can be found here.") @SuppressWarnings("NonJaxWsWebServices") @Produces({"application/json", "application/xml"}) @Consumes({ "application/json", "application/xml" }) diff --git a/components/device-mgt/org.wso2.carbon.device.mgt.api/src/main/java/org/wso2/carbon/device/mgt/jaxrs/api/DeviceSearch.java b/components/device-mgt/org.wso2.carbon.device.mgt.api/src/main/java/org/wso2/carbon/device/mgt/jaxrs/api/DeviceSearch.java index ec27086e36..5760813e07 100644 --- a/components/device-mgt/org.wso2.carbon.device.mgt.api/src/main/java/org/wso2/carbon/device/mgt/jaxrs/api/DeviceSearch.java +++ b/components/device-mgt/org.wso2.carbon.device.mgt.api/src/main/java/org/wso2/carbon/device/mgt/jaxrs/api/DeviceSearch.java @@ -34,7 +34,8 @@ import javax.ws.rs.core.Response; /** * Device search related operations such as getting device information. */ -@Api(value = "DeviceSearch") + +@Api(value = "DeviceSearch", description = "Device searching related operations can be found here.") @SuppressWarnings("NonJaxWsWebServices") public interface DeviceSearch { diff --git a/components/device-mgt/org.wso2.carbon.device.mgt.api/src/main/java/org/wso2/carbon/device/mgt/jaxrs/api/Feature.java b/components/device-mgt/org.wso2.carbon.device.mgt.api/src/main/java/org/wso2/carbon/device/mgt/jaxrs/api/Feature.java index 42f23ae3b9..5051c153fc 100644 --- a/components/device-mgt/org.wso2.carbon.device.mgt.api/src/main/java/org/wso2/carbon/device/mgt/jaxrs/api/Feature.java +++ b/components/device-mgt/org.wso2.carbon.device.mgt.api/src/main/java/org/wso2/carbon/device/mgt/jaxrs/api/Feature.java @@ -31,7 +31,8 @@ import javax.ws.rs.core.Response; /** * Features */ -@Api(value = "Feature") + +@Api(value = "Feature", description = "Feature management related operations can be found here.") @SuppressWarnings("NonJaxWsWebServices") @Produces({"application/json", "application/xml"}) @Consumes({"application/json", "application/xml"}) diff --git a/components/device-mgt/org.wso2.carbon.device.mgt.api/src/main/java/org/wso2/carbon/device/mgt/jaxrs/api/Operation.java b/components/device-mgt/org.wso2.carbon.device.mgt.api/src/main/java/org/wso2/carbon/device/mgt/jaxrs/api/Operation.java index 131eef9b2d..fb398dba68 100644 --- a/components/device-mgt/org.wso2.carbon.device.mgt.api/src/main/java/org/wso2/carbon/device/mgt/jaxrs/api/Operation.java +++ b/components/device-mgt/org.wso2.carbon.device.mgt.api/src/main/java/org/wso2/carbon/device/mgt/jaxrs/api/Operation.java @@ -36,7 +36,8 @@ import javax.ws.rs.core.Response; /** * */ -@Api(value = "Operation") + +@Api(value = "Operation", description = "Operation management related operations can be found here.") public interface Operation { /* @deprecated */ diff --git a/components/device-mgt/org.wso2.carbon.device.mgt.api/src/main/java/org/wso2/carbon/device/mgt/jaxrs/api/Policy.java b/components/device-mgt/org.wso2.carbon.device.mgt.api/src/main/java/org/wso2/carbon/device/mgt/jaxrs/api/Policy.java index 59ecc88a83..57a5521328 100644 --- a/components/device-mgt/org.wso2.carbon.device.mgt.api/src/main/java/org/wso2/carbon/device/mgt/jaxrs/api/Policy.java +++ b/components/device-mgt/org.wso2.carbon.device.mgt.api/src/main/java/org/wso2/carbon/device/mgt/jaxrs/api/Policy.java @@ -38,7 +38,8 @@ import java.util.List; /** * */ -@Api(value = "Policy") + +@Api(value = "Policy", description = "Policy management related operations can be found here.") public interface Policy { @POST diff --git a/components/device-mgt/org.wso2.carbon.device.mgt.api/src/main/java/org/wso2/carbon/device/mgt/jaxrs/api/Role.java b/components/device-mgt/org.wso2.carbon.device.mgt.api/src/main/java/org/wso2/carbon/device/mgt/jaxrs/api/Role.java index abf48eb8e5..a179d32e42 100644 --- a/components/device-mgt/org.wso2.carbon.device.mgt.api/src/main/java/org/wso2/carbon/device/mgt/jaxrs/api/Role.java +++ b/components/device-mgt/org.wso2.carbon.device.mgt.api/src/main/java/org/wso2/carbon/device/mgt/jaxrs/api/Role.java @@ -39,7 +39,7 @@ import java.util.List; /** * */ -@Api(value = "Role") +@Api(value = "Role", description = "Role management related operations can be found here.") public interface Role { @GET diff --git a/components/device-mgt/org.wso2.carbon.device.mgt.api/src/main/java/org/wso2/carbon/device/mgt/jaxrs/api/User.java b/components/device-mgt/org.wso2.carbon.device.mgt.api/src/main/java/org/wso2/carbon/device/mgt/jaxrs/api/User.java index d531fa25be..c3aefdbd82 100644 --- a/components/device-mgt/org.wso2.carbon.device.mgt.api/src/main/java/org/wso2/carbon/device/mgt/jaxrs/api/User.java +++ b/components/device-mgt/org.wso2.carbon.device.mgt.api/src/main/java/org/wso2/carbon/device/mgt/jaxrs/api/User.java @@ -44,7 +44,7 @@ import java.util.List; /** * This represents the JAX-RS services of User related functionality. */ -@Api(value = "User") +@Api(value = "User", description = "User management related operations can be found here.") public interface User { @POST diff --git a/components/device-mgt/org.wso2.carbon.device.mgt.api/src/main/java/org/wso2/carbon/device/mgt/jaxrs/beans/ApplicationWrapper.java b/components/device-mgt/org.wso2.carbon.device.mgt.api/src/main/java/org/wso2/carbon/device/mgt/jaxrs/beans/ApplicationWrapper.java index 4631e4e944..bb43a97643 100644 --- a/components/device-mgt/org.wso2.carbon.device.mgt.api/src/main/java/org/wso2/carbon/device/mgt/jaxrs/beans/ApplicationWrapper.java +++ b/components/device-mgt/org.wso2.carbon.device.mgt.api/src/main/java/org/wso2/carbon/device/mgt/jaxrs/beans/ApplicationWrapper.java @@ -18,14 +18,23 @@ package org.wso2.carbon.device.mgt.jaxrs.beans; +import io.swagger.annotations.ApiModel; +import io.swagger.annotations.ApiModelProperty; import org.wso2.carbon.device.mgt.common.DeviceIdentifier; import java.util.List; + +@ApiModel(value = "ApplicationWrapper", description = "Application details together with user, " + + "role or devices the application is associated with.") public class ApplicationWrapper { + @ApiModelProperty(name = "userNameList", value = "List of user names.", required = true ) private List userNameList; + @ApiModelProperty(name = "roleNameList", value = "List of role names.", required = true ) private List roleNameList; + @ApiModelProperty(name = "deviceIdentifiers", value = "List of device identifiers.", required = true ) private List deviceIdentifiers; + @ApiModelProperty(name = "application", value = "Details of the mobile application.", required = true ) private MobileApp application; public MobileApp getApplication() { diff --git a/components/device-mgt/org.wso2.carbon.device.mgt.api/src/main/java/org/wso2/carbon/device/mgt/jaxrs/beans/EnrollmentCertificate.java b/components/device-mgt/org.wso2.carbon.device.mgt.api/src/main/java/org/wso2/carbon/device/mgt/jaxrs/beans/EnrollmentCertificate.java index 40d94da4ed..d6a79db6f9 100644 --- a/components/device-mgt/org.wso2.carbon.device.mgt.api/src/main/java/org/wso2/carbon/device/mgt/jaxrs/beans/EnrollmentCertificate.java +++ b/components/device-mgt/org.wso2.carbon.device.mgt.api/src/main/java/org/wso2/carbon/device/mgt/jaxrs/beans/EnrollmentCertificate.java @@ -18,9 +18,19 @@ package org.wso2.carbon.device.mgt.jaxrs.beans; +import io.swagger.annotations.ApiModel; +import io.swagger.annotations.ApiModelProperty; + +@ApiModel(value = "EnrollmentCertificate", description = "Details of certificates used in enrollment.") public class EnrollmentCertificate { + + @ApiModelProperty(name = "serial", value = "The unique ID used to identify a certificate. This is the devices " + + "serial number in case of mutual SSL is used for enrollment.", + required = true ) String serial; + @ApiModelProperty(name = "pem", value = "Case 64 encode .pem file content.", required = true ) String pem; + @ApiModelProperty(name = "tenantId", value = "The ID of the tenant who adds the certificate.", required = true ) int tenantId; public int getTenantId() { diff --git a/components/device-mgt/org.wso2.carbon.device.mgt.api/src/main/java/org/wso2/carbon/device/mgt/jaxrs/beans/MobileApp.java b/components/device-mgt/org.wso2.carbon.device.mgt.api/src/main/java/org/wso2/carbon/device/mgt/jaxrs/beans/MobileApp.java index 7338f6141c..dd6a699c6c 100644 --- a/components/device-mgt/org.wso2.carbon.device.mgt.api/src/main/java/org/wso2/carbon/device/mgt/jaxrs/beans/MobileApp.java +++ b/components/device-mgt/org.wso2.carbon.device.mgt.api/src/main/java/org/wso2/carbon/device/mgt/jaxrs/beans/MobileApp.java @@ -18,24 +18,51 @@ package org.wso2.carbon.device.mgt.jaxrs.beans; +import io.swagger.annotations.ApiModel; +import io.swagger.annotations.ApiModelProperty; + import java.util.Properties; /** * This class represents the generic mobile AuthenticationImpl information * which is used by AppM. */ +@ApiModel(value = "ApplicationWrapper", description = "Details of a mobile application.") public class MobileApp { + @ApiModelProperty(name = "id", value = "Id of the app used internally.", required = true ) private String id; + @ApiModelProperty(name = "name", value = "The name of the application.", required = true ) private String name; + @ApiModelProperty(name = "type", value = "The type of the application. The following types of applications are " + + "supported: enterprise, public and webapp..", required = true ) private MobileAppTypes type; + @ApiModelProperty(name = "platform", value = "Platform the app can be installed on .", required = true ) private String platform; + @ApiModelProperty(name = "version", value = "Version of the application.", required = true ) private String version; + @ApiModelProperty(name = "identifier", value = "The package name of the application.", required = true ) private String identifier; + @ApiModelProperty(name = "iconImage", value = "Link to the icon of the app.", required = true ) private String iconImage; + @ApiModelProperty(name = "packageName", value = "Define the exact name of the application package. You can use one " + + "of the following methods to get the package name.\n" + + "Go to the respective application in the play store and copy the" + + " ID or package name from the URL.\n" + + "Example: The play store application URL for the Viber app is " + + "https://play.google.com/store/apps/details?id=com.viber.voip&hl=en." + + " Therefore, the package name or " + + "the application ID is: id=com.viber.voip \n" + + "Download the System Info for Android to your device from the" + + " play store. \n" + + "Once the application is successfully installed go to the Tasks " + + "tab and you will see the package name under the respective " + + "application..", required = true ) private String packageName; + @ApiModelProperty(name = "appIdentifier", value = "The package name of the application.", required = true ) private String appIdentifier; private String location; + @ApiModelProperty(name = "properties", value = "List of meta data.", required = true ) private Properties properties; public MobileAppTypes getType() { diff --git a/components/device-mgt/org.wso2.carbon.device.mgt.api/src/main/java/org/wso2/carbon/device/mgt/jaxrs/beans/UserCredentialWrapper.java b/components/device-mgt/org.wso2.carbon.device.mgt.api/src/main/java/org/wso2/carbon/device/mgt/jaxrs/beans/UserCredentialWrapper.java index d0c201b8d6..e5674b9de7 100644 --- a/components/device-mgt/org.wso2.carbon.device.mgt.api/src/main/java/org/wso2/carbon/device/mgt/jaxrs/beans/UserCredentialWrapper.java +++ b/components/device-mgt/org.wso2.carbon.device.mgt.api/src/main/java/org/wso2/carbon/device/mgt/jaxrs/beans/UserCredentialWrapper.java @@ -18,13 +18,20 @@ package org.wso2.carbon.device.mgt.jaxrs.beans; +import io.swagger.annotations.ApiModel; +import io.swagger.annotations.ApiModelProperty; + +@ApiModel(value = "UserCredentialWrapper", description = "User credentials are included in this class.") public class UserCredentialWrapper { + @ApiModelProperty(name = "username", value = "Username of the user.", required = true ) private String username; /* Base64 encoded password */ + @ApiModelProperty(name = "oldPassword", value = "Old password of the user.", required = true ) private String oldPassword; + @ApiModelProperty(name = "newPassword", value = "New password of the user.", required = true ) private String newPassword; public String getNewPassword() { diff --git a/components/device-mgt/org.wso2.carbon.device.mgt.api/src/main/java/org/wso2/carbon/device/mgt/jaxrs/beans/UserWrapper.java b/components/device-mgt/org.wso2.carbon.device.mgt.api/src/main/java/org/wso2/carbon/device/mgt/jaxrs/beans/UserWrapper.java index c03a762ee3..8009ae233e 100644 --- a/components/device-mgt/org.wso2.carbon.device.mgt.api/src/main/java/org/wso2/carbon/device/mgt/jaxrs/beans/UserWrapper.java +++ b/components/device-mgt/org.wso2.carbon.device.mgt.api/src/main/java/org/wso2/carbon/device/mgt/jaxrs/beans/UserWrapper.java @@ -18,16 +18,26 @@ package org.wso2.carbon.device.mgt.jaxrs.beans; +import io.swagger.annotations.ApiModel; +import io.swagger.annotations.ApiModelProperty; + +@ApiModel(value = "UserWrapper", description = "User details and the roles of the user.") public class UserWrapper { private String username; /* Base64 encoded password */ + + @ApiModelProperty(name = "password", value = "Base64 encoded password.", required = true ) private String password; + @ApiModelProperty(name = "firstname", value = "The first name of the user.", required = true ) private String firstname; + @ApiModelProperty(name = "lastname", value = "The last name of the user.", required = true ) private String lastname; + @ApiModelProperty(name = "emailAddress", value = "The email address of the user.", required = true ) private String emailAddress; + @ApiModelProperty(name = "roles", value = "List of roles.", required = true ) private String[] roles; public String getUsername() { diff --git a/components/device-mgt/org.wso2.carbon.device.mgt.common/src/main/java/org/wso2/carbon/device/mgt/common/notification/mgt/Notification.java b/components/device-mgt/org.wso2.carbon.device.mgt.common/src/main/java/org/wso2/carbon/device/mgt/common/notification/mgt/Notification.java index 0d3af9886d..f9f776222a 100644 --- a/components/device-mgt/org.wso2.carbon.device.mgt.common/src/main/java/org/wso2/carbon/device/mgt/common/notification/mgt/Notification.java +++ b/components/device-mgt/org.wso2.carbon.device.mgt.common/src/main/java/org/wso2/carbon/device/mgt/common/notification/mgt/Notification.java @@ -18,11 +18,15 @@ package org.wso2.carbon.device.mgt.common.notification.mgt; +import io.swagger.annotations.ApiModel; +import io.swagger.annotations.ApiModelProperty; import org.wso2.carbon.device.mgt.common.DeviceIdentifier; /** * DTO of Notification object which is used to communicate Operation notifications to MDM core. */ + +@ApiModel(value = "Notification", description = "This is used to communicate Operation notifications to MDM.") public class Notification { public enum Status{ @@ -33,10 +37,20 @@ public class Notification { ALERT, } + @ApiModelProperty(name = "notificationId", value = "Defines the notification ID.", required = true ) private int notificationId; + @ApiModelProperty(name = "deviceIdentifier", value = "Defines the device identification properties.", + required = true ) private DeviceIdentifier deviceIdentifier; + @ApiModelProperty(name = "description", value = "Provides the message you want to send to the user.", + required = true ) private String description; + @ApiModelProperty(name = "operationId", value = "Provides the operationID.", required = true ) private int operationId; + @ApiModelProperty(name = "status", value = "Provides the status of the message." + + "The following values can be assigned for the status.\n" + + "NEW: The message is in the unread state.\n" + + "CHECKED: The message is in the read state.", required = true ) private Status status; public Status getStatus() {