From 80117c24189ab0459523a3e541fe62725bd2b2a1 Mon Sep 17 00:00:00 2001 From: Massimiliano Assante Date: Tue, 1 Dec 2020 18:10:15 +0100 Subject: [PATCH] replaced previous version --- pom.xml | 20 +++++ .../liferay/ws/LiferayJSONWsCredentials.java | 2 +- .../networking/swagger/config/Bootstrap.java | 31 ++++++++ .../swagger/config/SwaggerConstants.java | 25 ++++++ .../social/networking/ws/SNLApiConfig.java | 47 ++++++++++++ .../networking/ws/inputs/ApplicationId.java | 12 ++- .../ws/inputs/JobNotificationBean.java | 31 +++++++- .../ws/inputs/MessageInputBean.java | 15 ++++ .../networking/ws/inputs/PostInputBean.java | 42 ++++++++-- .../networking/ws/inputs/Recipient.java | 9 ++- .../networking/ws/methods/v2/Comments.java | 26 ++++++- .../ws/methods/v2/FullTextSearch.java | 26 ++++++- .../networking/ws/methods/v2/HashTags.java | 15 ++++ .../networking/ws/methods/v2/Messages.java | 26 ++++++- .../ws/methods/v2/Notifications.java | 29 ++++++- .../networking/ws/methods/v2/People.java | 15 ++++ .../networking/ws/methods/v2/Posts.java | 76 ++++++++++++++++++- .../networking/ws/methods/v2/Tokens.java | 18 ++++- .../networking/ws/methods/v2/Users.java | 50 +++++++++++- .../social/networking/ws/methods/v2/VREs.java | 6 ++ .../networking/ws/outputs/ResponseBean.java | 9 ++- src/main/webapp/WEB-INF/web.xml | 2 +- 22 files changed, 500 insertions(+), 32 deletions(-) create mode 100644 src/main/java/org/gcube/portal/social/networking/swagger/config/Bootstrap.java create mode 100644 src/main/java/org/gcube/portal/social/networking/swagger/config/SwaggerConstants.java create mode 100644 src/main/java/org/gcube/portal/social/networking/ws/SNLApiConfig.java 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 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