diff --git a/pom.xml b/pom.xml
index e57636d..10f841d 100644
--- a/pom.xml
+++ b/pom.xml
@@ -221,26 +221,44 @@
org.glassfish.jersey.containers
jersey-container-servlet-core
+ ${version.jersey}
org.glassfish.jersey.media
jersey-media-json-jackson
+ ${version.jersey}
org.glassfish.jersey.media
jersey-media-json-processing
+ ${version.jersey}
org.glassfish.jersey.media
jersey-media-multipart
+ ${version.jersey}
org.glassfish.jersey.media
jersey-media-sse
+ ${version.jersey}
org.glassfish.jersey.ext
jersey-bean-validation
+ ${version.jersey}
+
+
+ io.swagger
+ swagger-jersey2-jaxrs
+ ${version.swagger}
+ provided
+
+
+ jackson-dataformat-yaml
+ com.fasterxml.jackson.dataformat
+
+
javax.portlet
@@ -287,6 +305,7 @@
org.apache.maven.plugins
maven-war-plugin
+ 2.1.1
compile
@@ -302,6 +321,7 @@
org.apache.maven.plugins
maven-compiler-plugin
+ 2.3.2
1.8
diff --git a/src/main/java/org/gcube/portal/social/networking/liferay/ws/LiferayJSONWsCredentials.java b/src/main/java/org/gcube/portal/social/networking/liferay/ws/LiferayJSONWsCredentials.java
index 8376594..6543a30 100644
--- a/src/main/java/org/gcube/portal/social/networking/liferay/ws/LiferayJSONWsCredentials.java
+++ b/src/main/java/org/gcube/portal/social/networking/liferay/ws/LiferayJSONWsCredentials.java
@@ -118,7 +118,7 @@ public class LiferayJSONWsCredentials {
ScopeProvider.instance.set(oldContext);
}
- logger.debug("Bean built " + toString());
+ logger.info("Bean built " + toString());
}
/**
diff --git a/src/main/java/org/gcube/portal/social/networking/swagger/config/Bootstrap.java b/src/main/java/org/gcube/portal/social/networking/swagger/config/Bootstrap.java
new file mode 100644
index 0000000..d33e196
--- /dev/null
+++ b/src/main/java/org/gcube/portal/social/networking/swagger/config/Bootstrap.java
@@ -0,0 +1,31 @@
+package org.gcube.portal.social.networking.swagger.config;
+
+import io.swagger.jaxrs.config.BeanConfig;
+
+import javax.servlet.ServletConfig;
+import javax.servlet.ServletException;
+import javax.servlet.http.HttpServlet;
+
+/**
+ * Configuration servlet for swagger.
+ * @author Costantino Perciante at ISTI-CNR
+ */
+@SuppressWarnings("serial")
+public class Bootstrap extends HttpServlet{
+
+ public static final String GCUBE_TOKEN_IN_QUERY_DEF = "gcube-token-query";
+ public static final String GCUBE_TOKEN_IN_HEADER_DEF = "gcube-token-header";
+
+ @Override
+ public void init(ServletConfig config) throws ServletException {
+
+ super.init(config);
+ BeanConfig beanConfig = new BeanConfig();
+ beanConfig.setResourcePackage("org.gcube.portal.social.networking.ws");
+ beanConfig.setPrettyPrint(true); // print pretty json
+ beanConfig.setHost("socialnetworking1.d4science.org");
+ beanConfig.setBasePath("social-networking-library-ws/rest");
+ beanConfig.setScan(true);
+
+ }
+}
\ No newline at end of file
diff --git a/src/main/java/org/gcube/portal/social/networking/swagger/config/SwaggerConstants.java b/src/main/java/org/gcube/portal/social/networking/swagger/config/SwaggerConstants.java
new file mode 100644
index 0000000..63fc6b6
--- /dev/null
+++ b/src/main/java/org/gcube/portal/social/networking/swagger/config/SwaggerConstants.java
@@ -0,0 +1,25 @@
+package org.gcube.portal.social.networking.swagger.config;
+
+/**
+ * Swagger constants
+ * @author Costantino Perciante at ISTI-CNR (costantino.perciante@isti.cnr.it)
+ */
+public class SwaggerConstants {
+
+ public static final String SECURITY_SCHEMA = "gcube-token";
+ public static final String HTTP_SCHEMA = "http";
+ public static final String HTTPS_SCHEMA = "https";
+
+ // VALUES
+ public static final String USERS = "users";
+ public static final String TOKENS = "tokens";
+ public static final String POSTS = "posts";
+ public static final String PEOPLE = "people";
+ public static final String NOTIFICATIONS = "notifications";
+ public static final String MESSAGES = "messages";
+ public static final String HASHTAGS = "hashtags";
+ public static final String FULLTEXT = "full-text-search";
+ public static final String COMMENTS = "comments";
+ public static final String VRES = "vres";
+
+}
\ No newline at end of file
diff --git a/src/main/java/org/gcube/portal/social/networking/ws/SNLApiConfig.java b/src/main/java/org/gcube/portal/social/networking/ws/SNLApiConfig.java
new file mode 100644
index 0000000..664c935
--- /dev/null
+++ b/src/main/java/org/gcube/portal/social/networking/ws/SNLApiConfig.java
@@ -0,0 +1,47 @@
+package org.gcube.portal.social.networking.ws;
+
+import org.gcube.portal.social.networking.swagger.config.Bootstrap;
+
+import io.swagger.annotations.ApiKeyAuthDefinition;
+import io.swagger.annotations.ApiKeyAuthDefinition.ApiKeyLocation;
+import io.swagger.annotations.Contact;
+import io.swagger.annotations.Extension;
+import io.swagger.annotations.ExtensionProperty;
+import io.swagger.annotations.ExternalDocs;
+import io.swagger.annotations.Info;
+import io.swagger.annotations.SecurityDefinition;
+import io.swagger.annotations.SwaggerDefinition;
+
+
+@SwaggerDefinition(
+ info = @Info(
+ description = "This is the official documentation of the second version (v. 2.0) of the Social-Networking RESTful interface.",
+ version = "V 2.0",
+ title = "Social Networking RESTful Service",
+ contact = @Contact(
+ name = "Costantino Perciante",
+ email ="costantino.perciante@isti.cnr.it"
+ ),
+ extensions = {
+ @Extension(name = "extra-contact", properties = {
+ @ExtensionProperty(name = "name", value = "Massimiliano Assante"),
+ @ExtensionProperty(name = "email", value = "massimiliano.assante@isti.cnr.it")
+ }),
+ @Extension(name = "development-host", properties = {
+ @ExtensionProperty(name = "url", value = "https://socialnetworking-d-d4s.d4science.org"),
+ })
+ }
+ ),
+ externalDocs=@ExternalDocs(url="https://wiki.gcube-system.org/gcube/Social_Networking_Service", value="Wiki page at gCube"),
+ host="socialnetworking1.d4science.org",
+ basePath="social-networking-library-ws/rest",
+ securityDefinition=@SecurityDefinition(
+ apiKeyAuthDefinitions={
+ @ApiKeyAuthDefinition(key=Bootstrap.GCUBE_TOKEN_IN_QUERY_DEF, description="A token bound to a user (or app identifier) and a context", in=ApiKeyLocation.HEADER, name="gcube-token"),
+ @ApiKeyAuthDefinition(key=Bootstrap.GCUBE_TOKEN_IN_HEADER_DEF, description="A token bound to a user (or app identifier) and a context", in=ApiKeyLocation.QUERY, name="gcube-token")
+ }),
+ schemes = {SwaggerDefinition.Scheme.HTTP, SwaggerDefinition.Scheme.HTTPS}
+ )
+public interface SNLApiConfig {
+
+}
diff --git a/src/main/java/org/gcube/portal/social/networking/ws/inputs/ApplicationId.java b/src/main/java/org/gcube/portal/social/networking/ws/inputs/ApplicationId.java
index ff43c13..58495d9 100644
--- a/src/main/java/org/gcube/portal/social/networking/ws/inputs/ApplicationId.java
+++ b/src/main/java/org/gcube/portal/social/networking/ws/inputs/ApplicationId.java
@@ -1,5 +1,8 @@
package org.gcube.portal.social.networking.ws.inputs;
+import io.swagger.annotations.ApiModel;
+import io.swagger.annotations.ApiModelProperty;
+
import javax.validation.constraints.NotNull;
import javax.validation.constraints.Size;
@@ -10,13 +13,18 @@ import com.fasterxml.jackson.annotation.JsonProperty;
* Application id object
* @author Costantino Perciante at ISTI-CNR
*/
-
+@ApiModel(description="An object containing the app_id field", value="Application")
public class ApplicationId {
@JsonProperty("app_id")
@NotNull(message="app_id cannot be null")
@Size(message="app_id cannot be empty", min=1)
-
+ @ApiModelProperty(
+ example="appX",
+ name="app_id",
+ required=true,
+ value="The application identifier"
+ )
private String appId;
public ApplicationId() {
diff --git a/src/main/java/org/gcube/portal/social/networking/ws/inputs/JobNotificationBean.java b/src/main/java/org/gcube/portal/social/networking/ws/inputs/JobNotificationBean.java
index e0de958..39a55ca 100644
--- a/src/main/java/org/gcube/portal/social/networking/ws/inputs/JobNotificationBean.java
+++ b/src/main/java/org/gcube/portal/social/networking/ws/inputs/JobNotificationBean.java
@@ -1,6 +1,7 @@
package org.gcube.portal.social.networking.ws.inputs;
-
+import io.swagger.annotations.ApiModel;
+import io.swagger.annotations.ApiModelProperty;
import javax.validation.constraints.NotNull;
@@ -18,31 +19,57 @@ import com.fasterxml.jackson.databind.annotation.JsonDeserialize;
* @author Costantino Perciante at ISTI-CNR (costantino.perciante@isti.cnr.it)
*/
@JsonIgnoreProperties(ignoreUnknown = true) // ignore in serialization/deserialization
-
+@ApiModel(description="A job notification object", value="JobNotification")
public class JobNotificationBean {
@JsonProperty("recipient")
@NotNull(message="recipient cannot be missing")
+ @ApiModelProperty(value="The recipient of the notification",
+ required=true,
+ example="andrea.rossi",
+ name="recipient")
private String recipient;
@JsonProperty("job_id")
+ @ApiModelProperty(value="The job's identifier, i.e. very likely a UUID",
+ required=true,
+ example="88055f18-558a-4246-942d-a43012528c92",
+ name="job_id")
@NotNull(message="job_id cannot be missing")
private String jobId;
@JsonProperty("job_name")
+ @ApiModelProperty(value="The job's name",
+ required=true,
+ example="SocialDataIndexer Plugin",
+ name="job_name")
@NotNull(message="job_name cannot be missing")
private String jobName;
@JsonProperty("service_name")
+ @ApiModelProperty(value="The name of the service running the job",
+ required=true,
+ example="SmartExecutor",
+ name="service_name")
@NotNull(message="service_name cannot be missing")
private String serviceName;
@JsonProperty("status")
+ @ApiModelProperty(value="The status of the job",
+ required=true,
+ example="FAILED",
+ name="status",
+ allowableValues = "CANCELLED,CANCELLING,DELETED,DELETING,EXECUTING,FAILED,NEW,SUBMITTED,SUCCEEDED,TIMED_OUT,WAITING"
+ )
@JsonDeserialize(using=JobStatusTypeDeserializer.class)
@NotNull(message="status cannot be missing")
private JobStatusType status;
@JsonProperty("status_message")
+ @ApiModelProperty(value="A message reporting the reason of the current status",
+ required=false,
+ example="An error occurred while ...",
+ name="status_message")
private String statusMessage;
public JobNotificationBean() {
diff --git a/src/main/java/org/gcube/portal/social/networking/ws/inputs/MessageInputBean.java b/src/main/java/org/gcube/portal/social/networking/ws/inputs/MessageInputBean.java
index 0e8698a..bf2792b 100644
--- a/src/main/java/org/gcube/portal/social/networking/ws/inputs/MessageInputBean.java
+++ b/src/main/java/org/gcube/portal/social/networking/ws/inputs/MessageInputBean.java
@@ -1,5 +1,8 @@
package org.gcube.portal.social.networking.ws.inputs;
+import io.swagger.annotations.ApiModel;
+import io.swagger.annotations.ApiModelProperty;
+
import java.io.Serializable;
import java.util.ArrayList;
@@ -15,6 +18,7 @@ import com.fasterxml.jackson.annotation.JsonProperty;
* @author Costantino Perciante at ISTI-CNR
*/
@JsonIgnoreProperties(ignoreUnknown = true) // ignore in serialization/deserialization
+@ApiModel(description="A message object", value="Message")
public class MessageInputBean implements Serializable {
private static final long serialVersionUID = -1317811686036127456L;
@@ -30,17 +34,28 @@ public class MessageInputBean implements Serializable {
@JsonProperty("body")
@NotNull(message="body cannot be missing")
@Size(min=1, message="body cannot be empty")
+ @ApiModelProperty(
+ example="This is the body of the mail ...",
+ required= true,
+ value="The body of the message")
private String body;
@JsonProperty("subject")
@NotNull(message="subject cannot be missing")
@Size(min=1, message="subject cannot be empty")
+ @ApiModelProperty(
+ example="This is the subject of the mail ...",
+ required= true,
+ value="The subject of the message")
private String subject;
@JsonProperty("recipients")
@NotNull(message="recipients cannot be missing")
@Size(min=1, message="at least a recipient is needed")
@Valid // validate recursively
+ @ApiModelProperty(
+ required= true,
+ value="The recipients of this message. At least one is needed")
private ArrayList recipients;
public MessageInputBean() {
diff --git a/src/main/java/org/gcube/portal/social/networking/ws/inputs/PostInputBean.java b/src/main/java/org/gcube/portal/social/networking/ws/inputs/PostInputBean.java
index f2c94d5..4e9f76c 100644
--- a/src/main/java/org/gcube/portal/social/networking/ws/inputs/PostInputBean.java
+++ b/src/main/java/org/gcube/portal/social/networking/ws/inputs/PostInputBean.java
@@ -1,5 +1,7 @@
package org.gcube.portal.social.networking.ws.inputs;
+import io.swagger.annotations.ApiModel;
+import io.swagger.annotations.ApiModelProperty;
import java.io.Serializable;
@@ -13,6 +15,7 @@ import com.fasterxml.jackson.annotation.JsonProperty;
* @author Costantino Perciante at ISTI-CNR
*/
@JsonIgnoreProperties(ignoreUnknown = true) // ignore in serialization/deserialization
+@ApiModel(description="A post object", value="Post")
public class PostInputBean implements Serializable{
private static final long serialVersionUID = 5274608088828232980L;
@@ -20,35 +23,58 @@ public class PostInputBean implements Serializable{
@JsonProperty("text")
@NotNull(message="text cannot be null")
@Size(min=1, message="text cannot be empty")
-
+ @ApiModelProperty(
+ example="Dear vre members, ...",
+ required=true,
+ value="The text of the post")
private String text;
@JsonProperty("preview_title")
-
+ @ApiModelProperty(
+ required=false,
+ value="A preview title for the preview",
+ name="preview_title")
private String previewtitle;
@JsonProperty("preview_description")
-
+ @ApiModelProperty(
+ required=false,
+ value="A preview description for the preview",
+ name="preview_description")
private String previewdescription;
@JsonProperty("preview_host")
-
+ @ApiModelProperty(
+ required=false,
+ value="A preview host for the preview",
+ name="preview_host")
private String previewhost;
@JsonProperty("preview_url")
-
+ @ApiModelProperty(
+ required=false,
+ value="A preview url for the preview",
+ name="preview_url")
private String previewurl;
@JsonProperty("image_url")
-
+ @ApiModelProperty(
+ required=false,
+ value="An image url for the preview",
+ name="image_url")
private String httpimageurl;
@JsonProperty("enable_notification")
-
+ @ApiModelProperty(
+ required=false,
+ value="If true send a notification to the other vre members about this post",
+ name="enable_notification")
private boolean enablenotification;
@JsonProperty("params")
-
+ @ApiModelProperty(
+ required=false,
+ value="Other parameters for the application's posts")
private String params;
public PostInputBean() {
diff --git a/src/main/java/org/gcube/portal/social/networking/ws/inputs/Recipient.java b/src/main/java/org/gcube/portal/social/networking/ws/inputs/Recipient.java
index f307f48..e375a7b 100644
--- a/src/main/java/org/gcube/portal/social/networking/ws/inputs/Recipient.java
+++ b/src/main/java/org/gcube/portal/social/networking/ws/inputs/Recipient.java
@@ -1,5 +1,7 @@
package org.gcube.portal.social.networking.ws.inputs;
+import io.swagger.annotations.ApiModel;
+import io.swagger.annotations.ApiModelProperty;
import java.io.Serializable;
@@ -16,7 +18,7 @@ import com.fasterxml.jackson.annotation.JsonProperty;
*
*/
@JsonIgnoreProperties(ignoreUnknown = true) // ignore in serialization/deserialization
-
+@ApiModel(description="A recipient object")
public class Recipient implements Serializable{
private static final long serialVersionUID = 1071412144446514138L;
@@ -24,7 +26,10 @@ public class Recipient implements Serializable{
@JsonProperty("id")
@NotNull(message="recipient id must not be null")
@Size(min=1, message="recipient id must not be empty")
-
+ @ApiModelProperty(
+ example="andrea.rossi",
+ required=true,
+ value="The id of the recipient")
private String id;
public Recipient() {
diff --git a/src/main/java/org/gcube/portal/social/networking/ws/methods/v2/Comments.java b/src/main/java/org/gcube/portal/social/networking/ws/methods/v2/Comments.java
index 351dd43..b21c06b 100644
--- a/src/main/java/org/gcube/portal/social/networking/ws/methods/v2/Comments.java
+++ b/src/main/java/org/gcube/portal/social/networking/ws/methods/v2/Comments.java
@@ -1,6 +1,13 @@
package org.gcube.portal.social.networking.ws.methods.v2;
+import io.swagger.annotations.Api;
+import io.swagger.annotations.ApiOperation;
+import io.swagger.annotations.ApiParam;
+import io.swagger.annotations.ApiResponse;
+import io.swagger.annotations.ApiResponses;
+import io.swagger.annotations.Authorization;
+
import java.util.List;
import javax.validation.ValidationException;
@@ -17,8 +24,11 @@ import org.gcube.common.authorization.library.provider.AuthorizationProvider;
import org.gcube.common.authorization.library.utils.Caller;
import org.gcube.common.scope.api.ScopeProvider;
import org.gcube.portal.databook.shared.Comment;
+import org.gcube.portal.social.networking.swagger.config.Bootstrap;
+import org.gcube.portal.social.networking.swagger.config.SwaggerConstants;
import org.gcube.portal.social.networking.ws.outputs.ResponseBean;
import org.gcube.portal.social.networking.ws.utils.CassandraConnection;
+import org.gcube.portal.social.networking.ws.utils.ErrorMessages;
import org.gcube.portal.social.networking.ws.utils.Filters;
import org.slf4j.LoggerFactory;
@@ -27,6 +37,7 @@ import org.slf4j.LoggerFactory;
* @author Costantino Perciante at ISTI-CNR
*/
@Path("2/comments")
+@Api(value=SwaggerConstants.COMMENTS, authorizations={@Authorization(value = Bootstrap.GCUBE_TOKEN_IN_QUERY_DEF), @Authorization(value = Bootstrap.GCUBE_TOKEN_IN_HEADER_DEF)})
/**
* Resource endpoint for Comment (version 2)
* @author Costantino Perciante at ISTI-CNR
@@ -40,7 +51,10 @@ public class Comments {
@GET
@Produces(MediaType.APPLICATION_JSON)
@Path("get-comments-user")
-
+ @ApiOperation(value = "Retrieve user's comments", response=ResponseBean.class, nickname="get-comments-user", notes="Retrieve the list of comments belonging to the owner of the token in the related context.")
+ @ApiResponses(value = {
+ @ApiResponse(code = 200, message = "The list of comments is put into the 'result' field", response = ResponseBean.class),
+ @ApiResponse(code = 500, message = ErrorMessages.ERROR_IN_API_RESULT, response=ResponseBean.class)})
public Response getCommentsUser() {
ResponseBean responseBean = new ResponseBean();
@@ -69,9 +83,19 @@ public class Comments {
@GET
@Produces(MediaType.APPLICATION_JSON)
@Path("get-comments-user-by-time")
+ @ApiOperation(value = "Retrieve user's comments and filter by date", notes="Retrieve comments of the gcube-token's owner in the context bound to the token itself and filter them by date",
+ response=ResponseBean.class, nickname="get-comments-user-by-time")
+ @ApiResponses(value = {
+ @ApiResponse(code = 200, message = "The list of comments is put into the 'result' field", response = ResponseBean.class),
+ @ApiResponse(code = 500, message = ErrorMessages.ERROR_IN_API_RESULT, response=ResponseBean.class)})
public Response getCommentsUserByTime(
@QueryParam("time")
@Min(value = 0, message="time cannot be negative")
+ @ApiParam(
+ allowableValues="range[0, infinity]",
+ required=true,
+ name="time",
+ value="the base time for filtering operation")
long timeInMillis
) throws ValidationException{
diff --git a/src/main/java/org/gcube/portal/social/networking/ws/methods/v2/FullTextSearch.java b/src/main/java/org/gcube/portal/social/networking/ws/methods/v2/FullTextSearch.java
index 99770f8..23bb40f 100644
--- a/src/main/java/org/gcube/portal/social/networking/ws/methods/v2/FullTextSearch.java
+++ b/src/main/java/org/gcube/portal/social/networking/ws/methods/v2/FullTextSearch.java
@@ -1,5 +1,12 @@
package org.gcube.portal.social.networking.ws.methods.v2;
+import io.swagger.annotations.Api;
+import io.swagger.annotations.ApiOperation;
+import io.swagger.annotations.ApiParam;
+import io.swagger.annotations.ApiResponse;
+import io.swagger.annotations.ApiResponses;
+import io.swagger.annotations.Authorization;
+
import java.util.ArrayList;
import java.util.HashSet;
import java.util.List;
@@ -28,9 +35,12 @@ import org.gcube.portal.databook.shared.EnhancedFeed;
import org.gcube.portal.databook.shared.Feed;
import org.gcube.portal.social.networking.liferay.ws.GroupManagerWSBuilder;
import org.gcube.portal.social.networking.liferay.ws.UserManagerWSBuilder;
+import org.gcube.portal.social.networking.swagger.config.Bootstrap;
+import org.gcube.portal.social.networking.swagger.config.SwaggerConstants;
import org.gcube.portal.social.networking.ws.outputs.ResponseBean;
import org.gcube.portal.social.networking.ws.utils.CassandraConnection;
import org.gcube.portal.social.networking.ws.utils.ElasticSearchConnection;
+import org.gcube.portal.social.networking.ws.utils.ErrorMessages;
import org.gcube.portal.social.networking.ws.utils.Filters;
import org.gcube.portal.social.networking.ws.utils.TokensUtils;
import org.gcube.vomanagement.usermanagement.GroupManager;
@@ -44,7 +54,7 @@ import org.slf4j.LoggerFactory;
* @author Costantino Perciante at ISTI-CNR
*/
@Path("2/full-text-search")
-
+@Api(value=SwaggerConstants.FULLTEXT, authorizations={@Authorization(value = Bootstrap.GCUBE_TOKEN_IN_QUERY_DEF), @Authorization(value = Bootstrap.GCUBE_TOKEN_IN_HEADER_DEF)})
public class FullTextSearch {
// Logger
@@ -53,18 +63,26 @@ public class FullTextSearch {
@GET
@Path("search-by-query")
@Produces(MediaType.APPLICATION_JSON)
+ @ApiOperation(value = "Retrieve posts/comments that match the given query",
+ notes="The posts/comments returned belong to the context bound to the gcube-token",
+ response=ResponseBean.class, nickname="search-by-query")
+ @ApiResponses(value = {
+ @ApiResponse(code = 200, message = "Successful retrieval of posts/comments that match the query, reported in the 'result' field of the returned object", response = ResponseBean.class),
+ @ApiResponse(code = 500, message = ErrorMessages.ERROR_IN_API_RESULT, response=ResponseBean.class)})
public Response searchByQuery(
@Context HttpServletRequest httpServletRequest,
@QueryParam("query") @NotNull(message="query cannot be null") @Size(min=1, message="query cannot be empty")
-
+ @ApiParam(required=true, defaultValue="none", name="query", value="A string to search for")
String query,
@DefaultValue("0") @QueryParam("from") @Min(value=0, message="from cannot be negative")
-
+ @ApiParam(allowableValues="range[0, infinity]",
+ required=false, name="from", value="the index of the base result to be returned")
int from,
@DefaultValue("10") @QueryParam("quantity") @Min(value=0, message="quantity cannot be negative")
-
+ @ApiParam(allowableValues="range[1, infinity]",
+ required=false, name="quantity", value="defines how many results are most are to be returned")
int quantity
) throws ValidationException{
diff --git a/src/main/java/org/gcube/portal/social/networking/ws/methods/v2/HashTags.java b/src/main/java/org/gcube/portal/social/networking/ws/methods/v2/HashTags.java
index 2bf4eac..d8e21d4 100644
--- a/src/main/java/org/gcube/portal/social/networking/ws/methods/v2/HashTags.java
+++ b/src/main/java/org/gcube/portal/social/networking/ws/methods/v2/HashTags.java
@@ -1,5 +1,11 @@
package org.gcube.portal.social.networking.ws.methods.v2;
+import io.swagger.annotations.Api;
+import io.swagger.annotations.ApiOperation;
+import io.swagger.annotations.ApiResponse;
+import io.swagger.annotations.ApiResponses;
+import io.swagger.annotations.Authorization;
+
import java.util.Map;
import javax.ws.rs.GET;
@@ -14,8 +20,11 @@ import org.gcube.common.authorization.library.utils.Caller;
import org.gcube.common.scope.api.ScopeProvider;
import org.gcube.portal.databook.server.DatabookStore;
import org.gcube.portal.social.networking.liferay.ws.GroupManagerWSBuilder;
+import org.gcube.portal.social.networking.swagger.config.Bootstrap;
+import org.gcube.portal.social.networking.swagger.config.SwaggerConstants;
import org.gcube.portal.social.networking.ws.outputs.ResponseBean;
import org.gcube.portal.social.networking.ws.utils.CassandraConnection;
+import org.gcube.portal.social.networking.ws.utils.ErrorMessages;
import org.slf4j.LoggerFactory;
/**
@@ -23,6 +32,7 @@ import org.slf4j.LoggerFactory;
* @author Costantino Perciante at ISTI-CNR
*/
@Path("2/hashtags")
+@Api(value=SwaggerConstants.HASHTAGS, authorizations={@Authorization(value = Bootstrap.GCUBE_TOKEN_IN_QUERY_DEF), @Authorization(value = Bootstrap.GCUBE_TOKEN_IN_HEADER_DEF)})
public class HashTags {
// Logger
@@ -31,6 +41,11 @@ public class HashTags {
@GET
@Path("get-hashtags-and-occurrences/")
@Produces({MediaType.APPLICATION_JSON})
+ @ApiOperation(value = "Retrieve hashtags", nickname="get-hashtags-and-occurrences",
+ notes="Retrieve hashtags in the context bound to the gcube-token", response=ResponseBean.class)
+ @ApiResponses(value = {
+ @ApiResponse(code = 200, message = "Hashtags and occurrences retrieved, reported in the 'result' field of the returned object", response = ResponseBean.class),
+ @ApiResponse(code = 500, message = ErrorMessages.ERROR_IN_API_RESULT, response=ResponseBean.class)})
public Response getHashTagsAndOccurrences(){
Caller caller = AuthorizationProvider.instance.get();
diff --git a/src/main/java/org/gcube/portal/social/networking/ws/methods/v2/Messages.java b/src/main/java/org/gcube/portal/social/networking/ws/methods/v2/Messages.java
index 7618908..6883699 100644
--- a/src/main/java/org/gcube/portal/social/networking/ws/methods/v2/Messages.java
+++ b/src/main/java/org/gcube/portal/social/networking/ws/methods/v2/Messages.java
@@ -1,5 +1,11 @@
package org.gcube.portal.social.networking.ws.methods.v2;
+import io.swagger.annotations.Api;
+import io.swagger.annotations.ApiOperation;
+import io.swagger.annotations.ApiParam;
+import io.swagger.annotations.ApiResponse;
+import io.swagger.annotations.ApiResponses;
+import io.swagger.annotations.Authorization;
import java.util.ArrayList;
import java.util.Collections;
@@ -35,7 +41,8 @@ import org.gcube.portal.notifications.thread.MessageNotificationsThread;
import org.gcube.portal.social.networking.caches.SocialNetworkingSiteFinder;
import org.gcube.portal.social.networking.liferay.ws.LiferayJSONWsCredentials;
import org.gcube.portal.social.networking.liferay.ws.UserManagerWSBuilder;
-
+import org.gcube.portal.social.networking.swagger.config.Bootstrap;
+import org.gcube.portal.social.networking.swagger.config.SwaggerConstants;
import org.gcube.portal.social.networking.ws.inputs.MessageInputBean;
import org.gcube.portal.social.networking.ws.inputs.Recipient;
import org.gcube.portal.social.networking.ws.outputs.ResponseBean;
@@ -52,6 +59,7 @@ import org.slf4j.LoggerFactory;
* (costantino.perciante@isti.cnr.it)
*/
@Path("2/messages")
+@Api(value=SwaggerConstants.MESSAGES, authorizations={@Authorization(value = Bootstrap.GCUBE_TOKEN_IN_QUERY_DEF), @Authorization(value = Bootstrap.GCUBE_TOKEN_IN_HEADER_DEF)})
public class Messages {
// Logger
@@ -61,9 +69,15 @@ public class Messages {
@Path("write-message/")
@Consumes(MediaType.APPLICATION_JSON)
@Produces(MediaType.APPLICATION_JSON)
+ @ApiOperation(value = "Write a message to another user", notes="Write a message to another user. The sender is the token's owner by default",
+ response=ResponseBean.class, nickname="write-message")
+ @ApiResponses(value = {
+ @ApiResponse(code = 200, message = "Successful write a message. Its id is reported in the 'result' field of the returned object", response = ResponseBean.class),
+ @ApiResponse(code = 500, message = ErrorMessages.ERROR_IN_API_RESULT, response=ResponseBean.class)})
public Response writeMessage(
@NotNull(message="Message to send is missing")
@Valid
+ @ApiParam(name="input", required=true, allowMultiple=false, value="The message to write")
MessageInputBean input,
@Context HttpServletRequest httpServletRequest) throws ValidationException, UserManagementSystemException, UserRetrievalFault{
@@ -155,6 +169,11 @@ public class Messages {
@GET
@Path("get-sent-messages")
@Produces(MediaType.APPLICATION_JSON)
+ @ApiOperation(value = "Retrieve the list of sent messages", notes="Retrieve the list of sent messages. The user is the token's owner by default",
+ response=ResponseBean.class, nickname="get-sent-messages")
+ @ApiResponses(value = {
+ @ApiResponse(code = 200, message = "Successful read of the sent messages, reported in the 'result' field of the returned object", response = ResponseBean.class),
+ @ApiResponse(code = 500, message = ErrorMessages.ERROR_IN_API_RESULT, response=ResponseBean.class)})
public Response getSentMessages(){
Caller caller = AuthorizationProvider.instance.get();
@@ -183,6 +202,11 @@ public class Messages {
@GET
@Path("get-received-messages")
@Produces(MediaType.APPLICATION_JSON)
+ @ApiOperation(value = "Retrieve the list of received messages", notes="Retrieve the list of received messages. The user is the token's owner by default",
+ response=ResponseBean.class, nickname="get-received-messages")
+ @ApiResponses(value = {
+ @ApiResponse(code = 200, message = "Successful read of the received messages, reported in the 'result' field of the returned object", response = ResponseBean.class),
+ @ApiResponse(code = 500, message = ErrorMessages.ERROR_IN_API_RESULT, response=ResponseBean.class)})
public Response getReceivedMessages(){
Caller caller = AuthorizationProvider.instance.get();
diff --git a/src/main/java/org/gcube/portal/social/networking/ws/methods/v2/Notifications.java b/src/main/java/org/gcube/portal/social/networking/ws/methods/v2/Notifications.java
index da10bbb..4881c12 100644
--- a/src/main/java/org/gcube/portal/social/networking/ws/methods/v2/Notifications.java
+++ b/src/main/java/org/gcube/portal/social/networking/ws/methods/v2/Notifications.java
@@ -1,5 +1,12 @@
package org.gcube.portal.social.networking.ws.methods.v2;
+import io.swagger.annotations.Api;
+import io.swagger.annotations.ApiOperation;
+import io.swagger.annotations.ApiParam;
+import io.swagger.annotations.ApiResponse;
+import io.swagger.annotations.ApiResponses;
+import io.swagger.annotations.Authorization;
+
import java.util.Arrays;
import java.util.List;
@@ -31,19 +38,21 @@ import org.gcube.portal.notifications.thread.JobStatusNotificationThread;
import org.gcube.portal.social.networking.caches.SocialNetworkingSiteFinder;
import org.gcube.portal.social.networking.liferay.ws.LiferayJSONWsCredentials;
import org.gcube.portal.social.networking.liferay.ws.UserManagerWSBuilder;
+import org.gcube.portal.social.networking.swagger.config.Bootstrap;
+import org.gcube.portal.social.networking.swagger.config.SwaggerConstants;
import org.gcube.portal.social.networking.ws.inputs.JobNotificationBean;
import org.gcube.portal.social.networking.ws.outputs.ResponseBean;
import org.gcube.portal.social.networking.ws.utils.CassandraConnection;
+import org.gcube.portal.social.networking.ws.utils.ErrorMessages;
import org.gcube.vomanagement.usermanagement.model.GCubeUser;
import org.slf4j.LoggerFactory;
-
-
/**
* REST interface for the social networking library (notifications).
* @author Costantino Perciante at ISTI-CNR
*/
@Path("2/notifications")
+@Api(value=SwaggerConstants.NOTIFICATIONS, authorizations={@Authorization(value = Bootstrap.GCUBE_TOKEN_IN_QUERY_DEF), @Authorization(value = Bootstrap.GCUBE_TOKEN_IN_HEADER_DEF)})
public class Notifications {
// Logger
@@ -52,10 +61,20 @@ public class Notifications {
@GET
@Path("get-range-notifications/")
@Produces(MediaType.APPLICATION_JSON)
+ @ApiOperation(value = "Retrieve user's notifications", notes="Retrieve notifications of the gcube-token's owner",
+ response=ResponseBean.class, nickname="get-range-notifications")
+ @ApiResponses(value = {
+ @ApiResponse(code = 200, message = "Notifications retrieved and reported in the 'result' field of the returned object", response = ResponseBean.class),
+ @ApiResponse(code = 500, message = ErrorMessages.ERROR_IN_API_RESULT, response=ResponseBean.class)})
public Response getRangeNotifications(
@DefaultValue("1") @QueryParam("from") @Min(value=1, message="from must be greater or equal to 1")
+ @ApiParam(allowableValues="range[0, infinity]",
+ required=false, allowMultiple=false, value="The base index notification")
int from,
+
@DefaultValue("10") @QueryParam("quantity") @Min(value=0, message="quantity must be greater or equal to 0")
+ @ApiParam(allowableValues="range[1, infinity]",
+ required=false, allowMultiple=false, value="Retrieve notifications up to this quantity")
int quantity
) throws ValidationException{
@@ -85,10 +104,16 @@ public class Notifications {
@POST
@Path("notify-job-status/")
+ @ApiOperation(value = "Send a JOB Notification", notes="Send a JOB notification to a given recipient",
+ response=ResponseBean.class, nickname="notify-job-status")
+ @ApiResponses(value = {
+ @ApiResponse(code = 200, message = "Notification is sent correctly", response = ResponseBean.class),
+ @ApiResponse(code = 500, message = ErrorMessages.ERROR_IN_API_RESULT, response=ResponseBean.class)})
@Consumes(MediaType.APPLICATION_JSON)
@Produces(MediaType.APPLICATION_JSON)
public Response notifyJobStatus(
@NotNull(message="input is missing")
+ @ApiParam(name="job", required=true, allowMultiple=false, value="The job bean")
@Valid JobNotificationBean job) throws ValidationException{
Caller caller = AuthorizationProvider.instance.get();
diff --git a/src/main/java/org/gcube/portal/social/networking/ws/methods/v2/People.java b/src/main/java/org/gcube/portal/social/networking/ws/methods/v2/People.java
index 7b91741..bc08843 100644
--- a/src/main/java/org/gcube/portal/social/networking/ws/methods/v2/People.java
+++ b/src/main/java/org/gcube/portal/social/networking/ws/methods/v2/People.java
@@ -1,5 +1,11 @@
package org.gcube.portal.social.networking.ws.methods.v2;
+import io.swagger.annotations.Api;
+import io.swagger.annotations.ApiOperation;
+import io.swagger.annotations.ApiResponse;
+import io.swagger.annotations.ApiResponses;
+import io.swagger.annotations.Authorization;
+
import java.util.ArrayList;
import java.util.HashMap;
import java.util.List;
@@ -18,7 +24,10 @@ import org.gcube.common.scope.api.ScopeProvider;
import org.gcube.portal.social.networking.liferay.ws.GroupManagerWSBuilder;
import org.gcube.portal.social.networking.liferay.ws.RoleManagerWSBuilder;
import org.gcube.portal.social.networking.liferay.ws.UserManagerWSBuilder;
+import org.gcube.portal.social.networking.swagger.config.Bootstrap;
+import org.gcube.portal.social.networking.swagger.config.SwaggerConstants;
import org.gcube.portal.social.networking.ws.outputs.ResponseBean;
+import org.gcube.portal.social.networking.ws.utils.ErrorMessages;
import org.gcube.portal.social.networking.ws.utils.TokensUtils;
import org.gcube.vomanagement.usermanagement.GroupManager;
import org.gcube.vomanagement.usermanagement.RoleManager;
@@ -33,12 +42,18 @@ import org.slf4j.LoggerFactory;
* @author Costantino Perciante at ISTI-CNR
*/
@Path("2/people")
+@Api(value=SwaggerConstants.PEOPLE, authorizations={@Authorization(value = Bootstrap.GCUBE_TOKEN_IN_QUERY_DEF), @Authorization(value = Bootstrap.GCUBE_TOKEN_IN_HEADER_DEF)})
public class People {
private static final org.slf4j.Logger logger = LoggerFactory.getLogger(People.class);
@GET
@Path("profile")
+ @ApiOperation(value = "Retrieve user's profile", notes="Retrieve the user's profile. The user in this case is the one bound to the token which can be of any kind (qualified, default)",
+ response=ResponseBean.class, nickname="profile")
+ @ApiResponses(value = {
+ @ApiResponse(code = 200, message = "Successful retrieval of user's profile, reported in the 'result' field of the returned object", response = ResponseBean.class),
+ @ApiResponse(code = 500, message = ErrorMessages.ERROR_IN_API_RESULT, response=ResponseBean.class)})
@Produces(MediaType.APPLICATION_JSON)
public Response getProfile(){
diff --git a/src/main/java/org/gcube/portal/social/networking/ws/methods/v2/Posts.java b/src/main/java/org/gcube/portal/social/networking/ws/methods/v2/Posts.java
index 8da7e93..257fa1b 100644
--- a/src/main/java/org/gcube/portal/social/networking/ws/methods/v2/Posts.java
+++ b/src/main/java/org/gcube/portal/social/networking/ws/methods/v2/Posts.java
@@ -1,5 +1,13 @@
package org.gcube.portal.social.networking.ws.methods.v2;
+
+import io.swagger.annotations.Api;
+import io.swagger.annotations.ApiOperation;
+import io.swagger.annotations.ApiParam;
+import io.swagger.annotations.ApiResponse;
+import io.swagger.annotations.ApiResponses;
+import io.swagger.annotations.Authorization;
+
import java.util.ArrayList;
import java.util.List;
@@ -24,6 +32,8 @@ import org.gcube.common.scope.api.ScopeProvider;
import org.gcube.portal.databook.server.DatabookStore;
import org.gcube.portal.databook.shared.ApplicationProfile;
import org.gcube.portal.databook.shared.Feed;
+import org.gcube.portal.social.networking.swagger.config.Bootstrap;
+import org.gcube.portal.social.networking.swagger.config.SwaggerConstants;
import org.gcube.portal.social.networking.ws.inputs.PostInputBean;
import org.gcube.portal.social.networking.ws.outputs.ResponseBean;
import org.gcube.portal.social.networking.ws.utils.CassandraConnection;
@@ -37,6 +47,7 @@ import org.slf4j.LoggerFactory;
* @author Costantino Perciante at ISTI-CNR
*/
@Path("2/posts")
+@Api(value=SwaggerConstants.POSTS, authorizations={@Authorization(value = Bootstrap.GCUBE_TOKEN_IN_QUERY_DEF), @Authorization(value = Bootstrap.GCUBE_TOKEN_IN_HEADER_DEF)})
public class Posts {
// Logger
@@ -45,8 +56,15 @@ public class Posts {
@GET
@Path("get-posts-user-since/")
@Produces(MediaType.APPLICATION_JSON)
+ @ApiOperation(value = "Retrieve user's posts", notes="Retrieve posts of the gcube-token's owner, and allow to filter them by time",
+ response=ResponseBean.class, nickname="get-posts-user-since")
+ @ApiResponses(value = {
+ @ApiResponse(code = 200, message = "Successful retrieval of posts, reported in the 'result' field of the returned object", response = ResponseBean.class),
+ @ApiResponse(code = 500, message = ErrorMessages.ERROR_IN_API_RESULT, response=ResponseBean.class)})
public Response getRecentPostsByUserAndDate(
@QueryParam("time") @Min(value = 0, message="time cannot be negative")
+ @ApiParam(allowableValues="range[0, infinity]", name="time",
+ required=true, allowMultiple=false, value="The reference time since when retrieving posts")
long timeInMillis
) throws ValidationException{
@@ -79,7 +97,11 @@ public class Posts {
@GET
@Path("get-posts-user/")
@Produces(MediaType.APPLICATION_JSON)
-
+ @ApiOperation(value = "Retrieve all user's posts", notes="Retrieve all posts of the gcube-token's owner",
+ response=ResponseBean.class, nickname="get-posts-user")
+ @ApiResponses(value = {
+ @ApiResponse(code = 200, message = "Successful retrieval of posts, reported in the 'result' field of the returned object", response = ResponseBean.class),
+ @ApiResponse(code = 500, message = ErrorMessages.ERROR_IN_API_RESULT, response=ResponseBean.class)})
public Response getAllPostsByUser() {
Caller caller = AuthorizationProvider.instance.get();
@@ -109,10 +131,17 @@ public class Posts {
@GET
@Path("get-posts-user-quantity/")
@Produces(MediaType.APPLICATION_JSON)
+ @ApiOperation(value = "Retrieve a given quantity of latest user's posts", notes="Retrieve a given quantity of latest posts of the gcube-token's owner",
+ response=ResponseBean.class, nickname="get-posts-user-quantity")
+ @ApiResponses(value = {
+ @ApiResponse(code = 200, message = "Successful retrieval of posts, reported in the 'result' field of the returned object", response = ResponseBean.class),
+ @ApiResponse(code = 500, message = ErrorMessages.ERROR_IN_API_RESULT, response=ResponseBean.class)})
public Response getQuantityPostsByUser(
@DefaultValue("10")
@QueryParam("quantity")
@Min(value=0, message="quantity cannot be negative")
+ @ApiParam(allowableValues="range[0, infinity]", name="quantity",
+ required=false, allowMultiple=false, value="How many posts needs to be retrieved at most")
int quantity) throws ValidationException{
Caller caller = AuthorizationProvider.instance.get();
@@ -149,9 +178,16 @@ public class Posts {
@Path("write-post-user")
@Consumes(MediaType.APPLICATION_JSON)
@Produces(MediaType.APPLICATION_JSON)
+ @ApiOperation(value = "Create a new user post", notes="Create a new user post having as owner the gcube-token's owner",
+ response=ResponseBean.class, nickname="write-post-user")
+ @ApiResponses(value = {
+ @ApiResponse(code = 201, message = "Successfull created, the new post is reported in the 'result' field of the returned object", response = ResponseBean.class),
+ @ApiResponse(code = 500, message = ErrorMessages.ERROR_IN_API_RESULT, response=ResponseBean.class)})
public Response writePostUser(
@NotNull(message="Post to write is missing")
@Valid
+ @ApiParam(name="post",
+ required=true, allowMultiple=false, value="The post to be written")
PostInputBean post) throws ValidationException{
logger.debug("Request of writing a feed coming from user " + post);
@@ -210,6 +246,12 @@ public class Posts {
@GET
@Path("get-posts-app/")
@Produces(MediaType.APPLICATION_JSON)
+ @ApiOperation(value = "Retrieve the application's posts", notes="Retrieve the application's posts belonging to the gcube-token's owner (i.e., an application)",
+ response=ResponseBean.class, nickname="get-posts-app")
+ @ApiResponses(value = {
+ @ApiResponse(code = 200, message = "Successfull retrieved posts, they are reported in the 'result' field of the returned object", response = ResponseBean.class),
+ @ApiResponse(code = 403, message = "There is no application profile with such token", response=ResponseBean.class),
+ @ApiResponse(code = 500, message = ErrorMessages.ERROR_IN_API_RESULT, response=ResponseBean.class)})
public Response getAllPostsByApp() {
Caller caller = AuthorizationProvider.instance.get();
@@ -253,9 +295,17 @@ public class Posts {
@Path("write-post-app")
@Consumes(MediaType.APPLICATION_JSON)
@Produces(MediaType.APPLICATION_JSON)
+ @ApiOperation(value = "Create a new application post", notes="Create a new application post having as owner-application the gcube-token's owner",
+ response=ResponseBean.class, nickname="write-post-app")
+ @ApiResponses(value = {
+ @ApiResponse(code = 201, message = "Successfull created, the new post is reported in the 'result' field of the returned object", response = ResponseBean.class),
+ @ApiResponse(code = 403, message = "There is no application profile with such token", response=ResponseBean.class),
+ @ApiResponse(code = 500, message = ErrorMessages.ERROR_IN_API_RESULT, response=ResponseBean.class)})
public Response writePostApp(
@NotNull(message="Post to write is null")
@Valid
+ @ApiParam(name="post",
+ required=true, allowMultiple=false, value="The post to be written")
PostInputBean post){
Caller caller = AuthorizationProvider.instance.get();
@@ -319,6 +369,11 @@ public class Posts {
@GET
@Path("get-posts-vre/")
@Produces(MediaType.APPLICATION_JSON)
+ @ApiOperation(value = "Retrieve vre's posts", notes="Retrieve all the posts in the context bound to the gcube-token",
+ response=ResponseBean.class, nickname="get-posts-vre")
+ @ApiResponses(value = {
+ @ApiResponse(code = 200, message = "Successfull retrieved posts, they are reported in the 'result' field of the returned object", response = ResponseBean.class),
+ @ApiResponse(code = 500, message = ErrorMessages.ERROR_IN_API_RESULT, response=ResponseBean.class)})
public Response getAllPostsByVRE() {
String scope = ScopeProvider.instance.get();
@@ -344,9 +399,16 @@ public class Posts {
@GET
@Path("get-posts-by-hashtag/")
@Produces({MediaType.APPLICATION_JSON})
+ @ApiOperation(value = "Retrieve posts containing the hashtag", notes="Retrieve posts containing the hashtag in the context bound to the gcube-token",
+ response=ResponseBean.class, nickname="get-posts-by-hashtag")
+ @ApiResponses(value = {
+ @ApiResponse(code = 200, message = "Successfull retrieved posts, they are reported in the 'result' field of the returned object", response = ResponseBean.class),
+ @ApiResponse(code = 500, message = ErrorMessages.ERROR_IN_API_RESULT, response=ResponseBean.class)})
public Response getPostsByHashTags(
@QueryParam("hashtag")
@NotNull(message="hashtag cannot be missing")
+ @ApiParam(name="hashtag",
+ required=true, allowMultiple=false, value="The hashtag to be contained within the posts")
String hashtag) throws ValidationException {
Caller caller = AuthorizationProvider.instance.get();
@@ -372,6 +434,11 @@ public class Posts {
@GET
@Path("get-id-liked-posts/")
@Produces({MediaType.APPLICATION_JSON})
+ @ApiOperation(value = "Retrieve ids (UUID) of the liked by the user", notes="Retrieve ids (UUID) of the liked by the user in the context bound to the gcube-token",
+ response=ResponseBean.class, nickname="get-id-liked-posts")
+ @ApiResponses(value = {
+ @ApiResponse(code = 200, message = "Successfull retrieved ids, they are reported in the 'result' field of the returned object", response = ResponseBean.class),
+ @ApiResponse(code = 500, message = ErrorMessages.ERROR_IN_API_RESULT, response=ResponseBean.class)})
public Response getAllLikedPostIdsByUser() {
Caller caller = AuthorizationProvider.instance.get();
@@ -403,10 +470,17 @@ public class Posts {
@GET
@Path("get-liked-posts/")
@Produces(MediaType.APPLICATION_JSON)
+ @ApiOperation(value = "Retrieve posts liked by the user", notes="Retrieve posts liked by the user (up to a given quantity) in the context bound to the gcube-token",
+ response=ResponseBean.class, nickname="get-liked-posts")
+ @ApiResponses(value = {
+ @ApiResponse(code = 200, message = "Successfull retrieved posts. They are reported in the 'result' field of the returned object", response = ResponseBean.class),
+ @ApiResponse(code = 500, message = ErrorMessages.ERROR_IN_API_RESULT, response=ResponseBean.class)})
public Response getAllLikedPostsByUser(
@DefaultValue("10")
@QueryParam("limit")
@Min(message="limit cannot be negative", value = 0)
+ @ApiParam(name="limit",
+ required=false, allowMultiple=false, value="The maximum number of posts to be retrieved")
int limit) throws ValidationException{
Caller caller = AuthorizationProvider.instance.get();
diff --git a/src/main/java/org/gcube/portal/social/networking/ws/methods/v2/Tokens.java b/src/main/java/org/gcube/portal/social/networking/ws/methods/v2/Tokens.java
index 4b95e44..ed721c6 100644
--- a/src/main/java/org/gcube/portal/social/networking/ws/methods/v2/Tokens.java
+++ b/src/main/java/org/gcube/portal/social/networking/ws/methods/v2/Tokens.java
@@ -1,6 +1,12 @@
package org.gcube.portal.social.networking.ws.methods.v2;
import static org.gcube.common.authorization.client.Constants.authorizationService;
+import io.swagger.annotations.Api;
+import io.swagger.annotations.ApiOperation;
+import io.swagger.annotations.ApiParam;
+import io.swagger.annotations.ApiResponse;
+import io.swagger.annotations.ApiResponses;
+import io.swagger.annotations.Authorization;
import javax.validation.Valid;
import javax.validation.ValidationException;
@@ -15,6 +21,8 @@ import javax.ws.rs.core.Response.Status;
import org.gcube.common.scope.api.ScopeProvider;
import org.gcube.portal.databook.shared.ApplicationProfile;
+import org.gcube.portal.social.networking.swagger.config.Bootstrap;
+import org.gcube.portal.social.networking.swagger.config.SwaggerConstants;
import org.gcube.portal.social.networking.ws.inputs.ApplicationId;
import org.gcube.portal.social.networking.ws.outputs.ResponseBean;
import org.gcube.portal.social.networking.ws.utils.ErrorMessages;
@@ -22,13 +30,12 @@ import org.gcube.portal.social.networking.ws.utils.SocialUtils;
import org.slf4j.LoggerFactory;
-
-
/**
* REST interface for the social networking library (tokens).
* @author Costantino Perciante at ISTI-CNR
*/
@Path("2/tokens")
+@Api(value=SwaggerConstants.TOKENS, authorizations={@Authorization(value = Bootstrap.GCUBE_TOKEN_IN_QUERY_DEF), @Authorization(value = Bootstrap.GCUBE_TOKEN_IN_HEADER_DEF)})
public class Tokens {
// Logger
@@ -38,9 +45,16 @@ public class Tokens {
@Path("generate-application-token/")
@Produces(MediaType.APPLICATION_JSON)
@Consumes(MediaType.APPLICATION_JSON)
+ @ApiOperation(value = "Generate an application token", notes="Generate an application token for the application with id app_id",
+ response=ResponseBean.class, nickname="generate-application-token")
+ @ApiResponses(value = {
+ @ApiResponse(code = 201, message = "Successful creation of the token, reported in the 'result' field of the returned object", response = ResponseBean.class),
+ @ApiResponse(code = 403, message = "There is no application profile with such id", response=ResponseBean.class),
+ @ApiResponse(code = 500, message = ErrorMessages.ERROR_IN_API_RESULT, response=ResponseBean.class)})
public Response generateApplicationToken(
@NotNull(message="Missing input parameter")
@Valid
+ @ApiParam(name="input", required=true, allowMultiple=false, value="The bean containing the app_id field")
ApplicationId input) throws ValidationException{
logger.debug("Incoming request for app token generation.");
diff --git a/src/main/java/org/gcube/portal/social/networking/ws/methods/v2/Users.java b/src/main/java/org/gcube/portal/social/networking/ws/methods/v2/Users.java
index 3bffc92..7d705a7 100644
--- a/src/main/java/org/gcube/portal/social/networking/ws/methods/v2/Users.java
+++ b/src/main/java/org/gcube/portal/social/networking/ws/methods/v2/Users.java
@@ -26,7 +26,10 @@ import org.gcube.portal.social.networking.caches.UsersCache;
import org.gcube.portal.social.networking.liferay.ws.GroupManagerWSBuilder;
import org.gcube.portal.social.networking.liferay.ws.RoleManagerWSBuilder;
import org.gcube.portal.social.networking.liferay.ws.UserManagerWSBuilder;
+import org.gcube.portal.social.networking.swagger.config.Bootstrap;
+import org.gcube.portal.social.networking.swagger.config.SwaggerConstants;
import org.gcube.portal.social.networking.ws.outputs.ResponseBean;
+import org.gcube.portal.social.networking.ws.utils.ErrorMessages;
import org.gcube.portal.social.networking.ws.utils.TokensUtils;
import org.gcube.portal.social.networking.ws.utils.UserProfileExtendedWithVerifiedEmail;
import org.gcube.vomanagement.usermanagement.GroupManager;
@@ -36,12 +39,19 @@ import org.gcube.vomanagement.usermanagement.model.GCubeRole;
import org.gcube.vomanagement.usermanagement.model.GCubeUser;
import org.slf4j.LoggerFactory;
+import io.swagger.annotations.Api;
+import io.swagger.annotations.ApiOperation;
+import io.swagger.annotations.ApiParam;
+import io.swagger.annotations.ApiResponse;
+import io.swagger.annotations.ApiResponses;
+import io.swagger.annotations.Authorization;
/**
* REST interface for the social networking library (users).
* @author Costantino Perciante at ISTI-CNR
*/
@Path("2/users")
+@Api(value=SwaggerConstants.USERS, authorizations={@Authorization(value = Bootstrap.GCUBE_TOKEN_IN_QUERY_DEF), @Authorization(value = Bootstrap.GCUBE_TOKEN_IN_HEADER_DEF)})
public class Users {
// Logger
@@ -52,10 +62,16 @@ public class Users {
@GET
@Path("get-custom-attribute/")
@Produces(MediaType.APPLICATION_JSON)
-
+ @ApiOperation(value = "Read a user's custom attribute", notes="Read a user's custom attribute. The user is the one owning the token",
+ response=ResponseBean.class, nickname="get-custom-attribute")
+ @ApiResponses(value = {
+ @ApiResponse(code = 200, message = "Successful read of the attribute, reported in the 'result' field of the returned object", response = ResponseBean.class),
+ @ApiResponse(code = 404, message = "Such an attribute doesn't exist", response = ResponseBean.class),
+ @ApiResponse(code = 500, message = ErrorMessages.ERROR_IN_API_RESULT, response=ResponseBean.class)})
public Response readCustomAttr(
@QueryParam("attribute")
@NotNull(message="attribute name is missing")
+ @ApiParam(name="attribute", required=true, allowMultiple=false, value="The key of the attribute to be read")
String attributeKey
) throws ValidationException {
@@ -146,6 +162,11 @@ public class Users {
@GET
@Path("get-fullname")
@Produces(MediaType.APPLICATION_JSON)
+ @ApiOperation(value = "Read the user's fullname", notes="Read the user's fullname. The user is the one owning the token",
+ response=ResponseBean.class, nickname="get-fullname")
+ @ApiResponses(value = {
+ @ApiResponse(code = 200, message = "The user's fullname is reported in the 'result' field of the returned object", response = ResponseBean.class),
+ @ApiResponse(code = 500, message = ErrorMessages.ERROR_IN_API_RESULT, response=ResponseBean.class)})
public Response getUserFullname(){
Caller caller = AuthorizationProvider.instance.get();
@@ -181,6 +202,11 @@ public class Users {
@GET
@Path("get-email")
@Produces(MediaType.APPLICATION_JSON)
+ @ApiOperation(value = "Read the user's email address", notes="Read the user's email address. The user is the one owning the token",
+ response=ResponseBean.class, nickname="get-email")
+ @ApiResponses(value = {
+ @ApiResponse(code = 200, message = "The user's email value is reported in the 'result' field of the returned object", response = ResponseBean.class),
+ @ApiResponse(code = 500, message = ErrorMessages.ERROR_IN_API_RESULT, response=ResponseBean.class)})
public Response getUserEmail(){
Caller caller = AuthorizationProvider.instance.get();
@@ -214,6 +240,11 @@ public class Users {
@GET
@Path("get-profile")
@Produces(MediaType.APPLICATION_JSON)
+ @ApiOperation(value = "Read the user's profile", notes="Read the user's profile. The user is the one owning the token",
+ response=ResponseBean.class, nickname="get-profile")
+ @ApiResponses(value = {
+ @ApiResponse(code = 200, message = "The user's profile is reported in the 'result' field of the returned object", response = ResponseBean.class),
+ @ApiResponse(code = 500, message = ErrorMessages.ERROR_IN_API_RESULT, response=ResponseBean.class)})
public Response getUserProfile(){
Caller caller = AuthorizationProvider.instance.get();
@@ -307,6 +338,11 @@ public class Users {
@GET
@Path("get-all-usernames")
+ @ApiOperation(value = "Get the list of usernames belonging to a given context", notes="Retrieve the list of usernames for the user belonging to the context linked to the provided token.",
+ response=ResponseBean.class, nickname="get-all-usernames")
+ @ApiResponses(value = {
+ @ApiResponse(code = 200, message = "The list of usernames is put into the 'result' field of the returned object", response = ResponseBean.class),
+ @ApiResponse(code = 500, message = ErrorMessages.ERROR_IN_API_RESULT, response=ResponseBean.class)})
@Produces(MediaType.APPLICATION_JSON)
public Response getAllUserNames(){
@@ -350,6 +386,11 @@ public class Users {
@GET
@Path("get-all-fullnames-and-usernames")
+ @ApiOperation(value = "Get the map of couples username/fullname of the users belonging to a given context", notes="Get the map of couples username/fullname of the users belonging to the context linked to the provided token.",
+ response=ResponseBean.class, nickname="get-all-fullnames-and-usernames")
+ @ApiResponses(value = {
+ @ApiResponse(code = 200, message = "The map is put into the 'result' field of the returned object", response = ResponseBean.class),
+ @ApiResponse(code = 500, message = ErrorMessages.ERROR_IN_API_RESULT, response=ResponseBean.class)})
@Produces(MediaType.APPLICATION_JSON)
public Response getFullnamesAndUsernames(){
@@ -393,9 +434,14 @@ public class Users {
@GET
@Path("get-usernames-by-global-role")
-
+ @ApiOperation(value = "Get the list of users having a given global-role", notes="Get the list of users having a given global-role, e.g. 'Administrator'.",
+ response=ResponseBean.class, nickname="get-usernames-by-global-role")
+ @ApiResponses(value = {
+ @ApiResponse(code = 200, message = "The list is put into the 'result' field of the returned object", response = ResponseBean.class),
+ @ApiResponse(code = 500, message = ErrorMessages.ERROR_IN_API_RESULT, response=ResponseBean.class)})
@Produces(MediaType.APPLICATION_JSON)
public Response getUsernamesByGlobalRole(
+ @ApiParam(value = "role-name: the name of the role to be checked (e.g. Administrator)", required = true)
@QueryParam("role-name") String roleName){
ResponseBean responseBean = new ResponseBean();
diff --git a/src/main/java/org/gcube/portal/social/networking/ws/methods/v2/VREs.java b/src/main/java/org/gcube/portal/social/networking/ws/methods/v2/VREs.java
index 31486d4..6efa424 100644
--- a/src/main/java/org/gcube/portal/social/networking/ws/methods/v2/VREs.java
+++ b/src/main/java/org/gcube/portal/social/networking/ws/methods/v2/VREs.java
@@ -1,5 +1,8 @@
package org.gcube.portal.social.networking.ws.methods.v2;
+import io.swagger.annotations.Api;
+import io.swagger.annotations.Authorization;
+
import java.util.List;
import javax.validation.ValidationException;
@@ -17,6 +20,8 @@ import org.gcube.common.authorization.library.utils.Caller;
import org.gcube.portal.social.networking.liferay.ws.GroupManagerWSBuilder;
import org.gcube.portal.social.networking.liferay.ws.RoleManagerWSBuilder;
import org.gcube.portal.social.networking.liferay.ws.UserManagerWSBuilder;
+import org.gcube.portal.social.networking.swagger.config.Bootstrap;
+import org.gcube.portal.social.networking.swagger.config.SwaggerConstants;
import org.gcube.portal.social.networking.ws.outputs.ResponseBean;
import org.gcube.portal.social.networking.ws.utils.TokensUtils;
import org.gcube.vomanagement.usermanagement.GroupManager;
@@ -35,6 +40,7 @@ import org.slf4j.LoggerFactory;
* @author Costantino Perciante at ISTI-CNR
*/
@Path("2/vres")
+@Api(value=SwaggerConstants.VRES, authorizations={@Authorization(value = Bootstrap.GCUBE_TOKEN_IN_QUERY_DEF), @Authorization(value = Bootstrap.GCUBE_TOKEN_IN_HEADER_DEF)})
public class VREs {
// Logger
diff --git a/src/main/java/org/gcube/portal/social/networking/ws/outputs/ResponseBean.java b/src/main/java/org/gcube/portal/social/networking/ws/outputs/ResponseBean.java
index 07c3c54..7a89c25 100644
--- a/src/main/java/org/gcube/portal/social/networking/ws/outputs/ResponseBean.java
+++ b/src/main/java/org/gcube/portal/social/networking/ws/outputs/ResponseBean.java
@@ -1,6 +1,7 @@
package org.gcube.portal.social.networking.ws.outputs;
-
+import io.swagger.annotations.ApiModel;
+import io.swagger.annotations.ApiModelProperty;
import java.io.Serializable;
@@ -10,15 +11,17 @@ import java.io.Serializable;
* (costantino.perciante@isti.cnr.it)
*
*/
+@ApiModel(description="A response object", value="Response")
public class ResponseBean implements Serializable {
private static final long serialVersionUID = -2725238162673879658L;
-
+ @ApiModelProperty(value="The result of the request: true if it succeeded, false otherwise")
private boolean success;
-
+ @ApiModelProperty(value="An error message if something wrong happened, null/empty otherwise")
private String message;
+ @ApiModelProperty(value="The result object of the request")
private Object result;
public ResponseBean() {
diff --git a/src/main/webapp/WEB-INF/web.xml b/src/main/webapp/WEB-INF/web.xml
index 8b2a3d4..9a8bd29 100644
--- a/src/main/webapp/WEB-INF/web.xml
+++ b/src/main/webapp/WEB-INF/web.xml
@@ -35,7 +35,7 @@
The token of the user J.A.R.V.I.S. on the portal (root context)
- e4b6d36d-ac40-47cb-a456-aa8b2fe59899-98187548
+ NOTIFIER_TOKEN