enriched docs

src/main/java/org/gcube/portal/social/networking/ws/inputs/Recipient.java

@@ -26,7 +26,7 @@ public class Recipient implements Serializable{
 	/*
 	 * @param "The recipient of the message",
 	 */
-	@DocumentationExample("andrea.rossi")
+	@DocumentationExample("john.smith")
 	private String id;
 
 	public Recipient() {

src/main/java/org/gcube/portal/social/networking/ws/methods/v2/Comments.java

@@ -23,6 +23,8 @@ import org.gcube.portal.social.networking.ws.utils.ErrorMessages;
 import org.gcube.portal.social.networking.ws.utils.Filters;
 import org.slf4j.LoggerFactory;
 
+import com.webcohesion.enunciate.metadata.rs.RequestHeader;
+import com.webcohesion.enunciate.metadata.rs.RequestHeaders;
 import com.webcohesion.enunciate.metadata.rs.ResponseCode;
 import com.webcohesion.enunciate.metadata.rs.StatusCodes;
 
@@ -30,11 +32,10 @@ import com.webcohesion.enunciate.metadata.rs.StatusCodes;
  * REST interface for the social networking library (comments).
  */
 @Path("2/comments")
-/**
+@RequestHeaders ({
- * Resource endpoint for Comment (version 2)
+	  @RequestHeader( name = "Authorization", description = "Bearer token, see https://dev.d4science.org/how-to-access-resources"),
- * @author Costantino Perciante at ISTI-CNR 
+	  @RequestHeader( name = "Content-Type", description = "application/json")	  
- * (costantino.perciante@isti.cnr.it)
+	})
- */
 public class Comments {
 
 	// Logger

src/main/java/org/gcube/portal/social/networking/ws/methods/v2/FullTextSearch.java

@@ -40,6 +40,8 @@ import org.gcube.vomanagement.usermanagement.model.GCubeGroup;
 import org.gcube.vomanagement.usermanagement.model.GCubeUser;
 import org.slf4j.LoggerFactory;
 
+import com.webcohesion.enunciate.metadata.rs.RequestHeader;
+import com.webcohesion.enunciate.metadata.rs.RequestHeaders;
 import com.webcohesion.enunciate.metadata.rs.ResponseCode;
 import com.webcohesion.enunciate.metadata.rs.StatusCodes;
 
@@ -47,6 +49,10 @@ import com.webcohesion.enunciate.metadata.rs.StatusCodes;
  * REST interface for the social networking library (post and its comments).
  */
 @Path("2/full-text-search")
+@RequestHeaders ({
+	  @RequestHeader( name = "Authorization", description = "Bearer token, see https://dev.d4science.org/how-to-access-resources"),
+	  @RequestHeader( name = "Content-Type", description = "application/json")	  
+	})
 public class FullTextSearch {
 
 	// Logger

src/main/java/org/gcube/portal/social/networking/ws/methods/v2/HashTags.java

@@ -19,14 +19,19 @@ import org.gcube.portal.social.networking.ws.utils.CassandraConnection;
 import org.gcube.portal.social.networking.ws.utils.ErrorMessages;
 import org.slf4j.LoggerFactory;
 
+import com.webcohesion.enunciate.metadata.rs.RequestHeader;
+import com.webcohesion.enunciate.metadata.rs.RequestHeaders;
 import com.webcohesion.enunciate.metadata.rs.ResponseCode;
 import com.webcohesion.enunciate.metadata.rs.StatusCodes;
 
 /**
  * REST interface for the social networking library (hash tags).
- * @author Costantino Perciante at ISTI-CNR
  */
 @Path("2/hashtags")
+@RequestHeaders ({
+	  @RequestHeader( name = "Authorization", description = "Bearer token, see https://dev.d4science.org/how-to-access-resources"),
+	  @RequestHeader( name = "Content-Type", description = "application/json")	  
+	})
 public class HashTags {
 
 	// Logger

src/main/java/org/gcube/portal/social/networking/ws/methods/v2/Messages.java

@@ -44,6 +44,8 @@ import org.gcube.vomanagement.usermanagement.exception.UserRetrievalFault;
 import org.gcube.vomanagement.usermanagement.model.GCubeUser;
 import org.slf4j.LoggerFactory;
 
+import com.webcohesion.enunciate.metadata.rs.RequestHeader;
+import com.webcohesion.enunciate.metadata.rs.RequestHeaders;
 import com.webcohesion.enunciate.metadata.rs.ResponseCode;
 import com.webcohesion.enunciate.metadata.rs.StatusCodes;
 
@@ -53,11 +55,25 @@ import com.webcohesion.enunciate.metadata.rs.StatusCodes;
  * (costantino.perciante@isti.cnr.it)
  */
 @Path("2/messages")
+@RequestHeaders ({
+	  @RequestHeader( name = "Authorization", description = "Bearer token, see https://dev.d4science.org/how-to-access-resources"),
+	  @RequestHeader( name = "Content-Type", description = "application/json")	  
+	})
 public class Messages {
 
 	// Logger
 	private static final org.slf4j.Logger logger = LoggerFactory.getLogger(Messages.class);
 
+	/**
+	 * Write a message to another user. The sender is the token's owner by default
+	 * @responseExample application/json {"success": true, "message": null, "result": "556142e3-d6f5-4550-b2fa-abe5626625d3"}
+	 * @param input The message to write"
+	 * @param httpServletRequest
+	 * @return see response example
+	 * @throws ValidationException
+	 * @throws UserManagementSystemException
+	 * @throws UserRetrievalFault
+	 */
 	@POST
 	@Path("write-message/")
 	@Consumes(MediaType.APPLICATION_JSON)
@@ -66,15 +82,6 @@ public class Messages {
 		@ResponseCode ( code = 200, condition = "Successful write a message. Its id is reported in the 'result' field of the returned object"),
 		@ResponseCode ( code = 500, condition = ErrorMessages.ERROR_IN_API_RESULT)
 	})
-	/**
-	 * Write a message to another user. The sender is the token's owner by default
-	 * @param input The message to write"
-	 * @param httpServletRequest
-	 * @return
-	 * @throws ValidationException
-	 * @throws UserManagementSystemException
-	 * @throws UserRetrievalFault
-	 */
 	public Response writeMessage(
 			@NotNull(message="Message to send is missing") 
 			@Valid 

src/main/java/org/gcube/portal/social/networking/ws/methods/v2/Notifications.java

@@ -38,14 +38,19 @@ import org.gcube.portal.social.networking.ws.utils.ErrorMessages;
 import org.gcube.vomanagement.usermanagement.model.GCubeUser;
 import org.slf4j.LoggerFactory;
 
+import com.webcohesion.enunciate.metadata.rs.RequestHeader;
+import com.webcohesion.enunciate.metadata.rs.RequestHeaders;
 import com.webcohesion.enunciate.metadata.rs.ResponseCode;
 import com.webcohesion.enunciate.metadata.rs.StatusCodes;
 
 /**
  * REST interface for the social networking library (notifications).
- * @author Costantino Perciante at ISTI-CNR
  */
 @Path("2/notifications")
+@RequestHeaders ({
+	  @RequestHeader( name = "Authorization", description = "Bearer token, see https://dev.d4science.org/how-to-access-resources"),
+	  @RequestHeader( name = "Content-Type", description = "application/json")	  
+	})
 public class Notifications {
 
 	// Logger

src/main/java/org/gcube/portal/social/networking/ws/methods/v2/People.java

@@ -26,14 +26,19 @@ import org.gcube.vomanagement.usermanagement.model.GCubeRole;
 import org.gcube.vomanagement.usermanagement.model.GCubeUser;
 import org.slf4j.LoggerFactory;
 
+import com.webcohesion.enunciate.metadata.rs.RequestHeader;
+import com.webcohesion.enunciate.metadata.rs.RequestHeaders;
 import com.webcohesion.enunciate.metadata.rs.ResponseCode;
 import com.webcohesion.enunciate.metadata.rs.StatusCodes;
 
 
 /**
- * REST interface for the social networking library (people). Used by OAUTH 2.0 apps/users.
+ * REST interface for the social service (people). Used by OAUTH 2.0 apps/users.
- * @author Costantino Perciante at ISTI-CNR
  */
+@RequestHeaders ({
+	  @RequestHeader( name = "Authorization", description = "Bearer token, see https://dev.d4science.org/how-to-access-resources"),
+	  @RequestHeader( name = "Content-Type", description = "application/json")	  
+	})
 @Path("2/people")
 public class People {
 
@@ -46,7 +51,7 @@ public class People {
 		@ResponseCode ( code = 500, condition = ErrorMessages.ERROR_IN_API_RESULT)
 	})
 	/**
-	 * 
+	 * @responseExample application/json { "success" : true, "message" : null, "result" : { "roles" : [ ], "context" : "***", "avatar" : "https://*****3D", "fullname" : "John Smith", "username" : "john.smith" } }
 	 * @return the user's profile. The user in this case is the one bound to the token
 	 */
 	public Response getProfile(){

src/main/java/org/gcube/portal/social/networking/ws/methods/v2/Posts.java

@@ -33,14 +33,19 @@ import org.gcube.portal.social.networking.ws.utils.Filters;
 import org.gcube.portal.social.networking.ws.utils.SocialUtils;
 import org.slf4j.LoggerFactory;
 
+import com.webcohesion.enunciate.metadata.rs.RequestHeader;
+import com.webcohesion.enunciate.metadata.rs.RequestHeaders;
 import com.webcohesion.enunciate.metadata.rs.ResponseCode;
 import com.webcohesion.enunciate.metadata.rs.StatusCodes;
 
 /**
- * REST interface for the social networking library (feeds).
+ * REST interface for the social networking library (posts).
- * @author Costantino Perciante at ISTI-CNR
  */
 @Path("2/posts")
+@RequestHeaders ({
+	  @RequestHeader( name = "Authorization", description = "Bearer token, see https://dev.d4science.org/how-to-access-resources"),
+	  @RequestHeader( name = "Content-Type", description = "application/json")	  
+	})
 public class Posts {
 
 	// Logger

src/main/java/org/gcube/portal/social/networking/ws/methods/v2/Tokens.java

@@ -27,9 +27,9 @@ import com.webcohesion.enunciate.metadata.rs.StatusCodes;
 
 /**
  * REST interface for the social networking library (tokens).
- * @author Costantino Perciante at ISTI-CNR
  */
 @Path("2/tokens")
+@Deprecated
 public class Tokens {
 
 	// Logger

src/main/java/org/gcube/portal/social/networking/ws/methods/v2/Users.java

@@ -37,14 +37,19 @@ import org.gcube.vomanagement.usermanagement.model.GCubeRole;
 import org.gcube.vomanagement.usermanagement.model.GCubeUser;
 import org.slf4j.LoggerFactory;
 
+import com.webcohesion.enunciate.metadata.rs.RequestHeader;
+import com.webcohesion.enunciate.metadata.rs.RequestHeaders;
 import com.webcohesion.enunciate.metadata.rs.ResponseCode;
 import com.webcohesion.enunciate.metadata.rs.StatusCodes;
 
 /**
  * REST interface for the social networking library (users).
- * @author Costantino Perciante at ISTI-CNR
  */
 @Path("2/users")
+@RequestHeaders ({
+	  @RequestHeader( name = "Authorization", description = "Bearer token, see https://dev.d4science.org/how-to-access-resources"),
+	  @RequestHeader( name = "Content-Type", description = "application/json")	  
+	})
 public class Users {
 
 	// Logger
@@ -186,6 +191,11 @@ public class Users {
 		return Response.status(status).entity(responseBean).build();
 	}
 
+	/**
+	 * Get the profile associated to the token
+	 * @responseExample application/json { "success" : true, "message" : null, "result" : { "user_id" : 23769487, "username" : "john.smith", "email" : "********", "first_name" : "John", "middle_name" : "", "last_name" : "Smith", "fullname" : "John Smith", "registration_date" : 1475151491415, "user_avatar_url" : "https://******D", "male" : true, "job_title" : "", "location_industry" : "no", "custom_attrs_map" : null, "email_addresses" : [ ], "screen_name" : "john.smith", "user_avatar_id" : "https://****sY%3D" } }
+	 * @return the user's profile. The user is the one owning the token
+	 */
 	@GET
 	@Path("get-profile")
 	@Produces(MediaType.APPLICATION_JSON)
@@ -193,10 +203,6 @@ public class Users {
 		@ResponseCode ( code = 200, condition = "The user's profile is reported in the 'result' field of the returned object"),
 		@ResponseCode ( code = 500, condition = ErrorMessages.ERROR_IN_API_RESULT)
 	})
-	/**
-	 * 
-	 * @return the user's profile. The user is the one owning the token
-	 */
 	public Response getUserProfile(){
 
 		Caller caller = AuthorizationProvider.instance.get();
@@ -246,6 +252,23 @@ public class Users {
 		}
 	};
 	
+	/**
+	 * @responseExample application/json {
+    "id": "john.smith",
+    "roles": [],
+    "picture": "https://***gAJ4uVWTA74xwQ6%2FCA72RRinysY%3D",
+    "name": "John Smith",
+    "middle_name": "",
+    "male": true,
+    "location_industry": "no",
+    "given_name": "John",
+    "email": "******",
+    "job_title": "",
+    "family_name": "Smith",
+    "verified_email": true
+}
+	 * @return the user's profile compliant with oauth
+	 */
 	@GET
 	@Path("get-oauth-profile")
 	@Produces(MediaType.APPLICATION_JSON)
@@ -287,7 +310,18 @@ public class Users {
 		return Response.status(status).entity(userWithEmailVerified).build();
 	}
 
-
+	/**
+	 *  @responseExample application/json {
+    "success": true,
+    "message": null,
+    "result": [
+        "john.smith",
+        "marco.polo"
+    ]
+}
+	 * Get the list of usernames belonging to a given context
+	 * @return the list of usernames for the user belonging to the context linked to the provided auth token
+	 */
 	@GET
 	@Path("get-all-usernames")
 	@Produces(MediaType.APPLICATION_JSON)
@@ -295,10 +329,6 @@ public class Users {
 		@ResponseCode ( code = 200, condition = "The list of usernames is put into the 'result' field of the returned object"),
 		@ResponseCode ( code = 500, condition = ErrorMessages.ERROR_IN_API_RESULT)
 	})
-	/**
-	 * Get the list of usernames belonging to a given context
-	 * @return the list of usernames for the user belonging to the context linked to the provided auth token
-	 */
 	public Response getAllUserNames(){
 
 		ResponseBean responseBean = new ResponseBean();
@@ -338,7 +368,11 @@ public class Users {
 
 		return Response.status(status).entity(responseBean).build();
 	}
-
+	
+	/**
+	 * Get the map of couples username/fullname of the users belonging to a given context
+	 * @return the map of couples username/fullname of the users belonging to the context linked to the provided token.
+	 */
 	@GET
 	@Path("get-all-fullnames-and-usernames")
 	@StatusCodes ({
@@ -346,10 +380,6 @@ public class Users {
 		@ResponseCode ( code = 500, condition = ErrorMessages.ERROR_IN_API_RESULT)
 	})
 	@Produces(MediaType.APPLICATION_JSON)
-	/**
-	 * Get the map of couples username/fullname of the users belonging to a given context
-	 * @return the map of couples username/fullname of the users belonging to the context linked to the provided token.
-	 */
 	public Response getFullnamesAndUsernames(){
 
 		ResponseBean responseBean = new ResponseBean();
@@ -390,6 +420,11 @@ public class Users {
 		return Response.status(status).entity(responseBean).build();
 	}
 
+	/**
+	 * Get the list of users having a given global-role, e.g. 'Administrator'. (Legacy)
+	 * @param roleName the name of the role to be checked (e.g. Administrator)
+	 * @return the list of users having a given global-role
+	 */
 	@GET
 	@Path("get-usernames-by-global-role")
 	@Produces(MediaType.APPLICATION_JSON)
@@ -397,11 +432,6 @@ public class Users {
 		@ResponseCode ( code = 200, condition = "The list is put into the 'result' field of the returned object"),
 		@ResponseCode ( code = 500, condition = ErrorMessages.ERROR_IN_API_RESULT)
 	})
-	/**
-	 * Get the list of users having a given global-role, e.g. 'Administrator'. (Legacy)
-	 * @param roleName the name of the role to be checked (e.g. Administrator)
-	 * @return the list of users having a given global-role
-	 */
 	public Response getUsernamesByGlobalRole(
 			@QueryParam("role-name") String roleName){
 
@@ -443,12 +473,24 @@ public class Users {
 		return Response.status(status).entity(responseBean).build();
 	}
 
+	/**
+	 * @pathExample /get-usernames-by-role?role-name=VRE-Manager
+	 * @param roleName the role name
+	 * @return the usernames having the role in the VRE
+	 * @responseExample application/json {
+    "success": true,
+    "message": null,
+    "result": [
+        "john.smith",
+        "marco.polo"
+    ]
+}
+	 */
 	@GET
 	@Path("get-usernames-by-role")
 	@Produces(MediaType.APPLICATION_JSON)
 	public Response getUsernamesByRole(
 			@QueryParam("role-name") String roleName){
-
 		ResponseBean responseBean = new ResponseBean();
 		Status status = Status.OK;
 		String context = ScopeProvider.instance.get();
@@ -500,6 +542,7 @@ public class Users {
 	@GET
 	@Path("user-exists")
 	@Produces(MediaType.APPLICATION_JSON)
+	@Deprecated
 	public Response existUser(@QueryParam("username") String username){
 
 		ResponseBean responseBean = new ResponseBean();

src/main/java/org/gcube/portal/social/networking/ws/methods/v2/VREs.java

@@ -29,17 +29,42 @@ import org.json.simple.JSONArray;
 import org.json.simple.JSONObject;
 import org.slf4j.LoggerFactory;
 
+import com.webcohesion.enunciate.metadata.rs.RequestHeader;
+import com.webcohesion.enunciate.metadata.rs.RequestHeaders;
+
 
 /**
  * REST interface for the social networking library (vres).
- * @author Costantino Perciante at ISTI-CNR
  */
 @Path("2/vres")
+@RequestHeaders ({
+	  @RequestHeader( name = "Authorization", description = "Bearer token, see https://dev.d4science.org/how-to-access-resources"),
+	  @RequestHeader( name = "Content-Type", description = "application/json")	  
+	})
 public class VREs {
 
 	// Logger
 	private static final org.slf4j.Logger logger = LoggerFactory.getLogger(Users.class);
 
+	/**
+	 * @responseExample application/json {
+  "success" : true,
+  "message" : null,
+  "result" : [ {
+    "name" : "NextNext",
+    "context" : "/gcube/devNext/NextNext",
+    "description" : "NextNext description  AAA"
+  }, {
+    "name" : "devVRE",
+    "context" : "/gcube/devsec/devVRE",
+    "description" : "devVRE description  BBB"
+  } ]
+}
+	 * @pathExample /get-my-vres?getManagers=false
+	 * @param getManagers set true if you also want to know the VRE-Managers
+	 * @return the list of vres along with some metadata
+	 * @throws ValidationException
+	 */
 	@SuppressWarnings("unchecked")
 	@GET
 	@Path("get-my-vres/")