Improved docs

src/main/java/org/gcube/gcat/rest/administration/Configuration.java

@@ -48,6 +48,8 @@ import com.webcohesion.enunciate.metadata.swagger.OperationId;
  * The catalogue configuration for the context of the request 
  * (i.e. the context where the token has been generated).
  * 
+ * Only Catalogue-Managers are able to invoke non-safe methods.
+ *  
  * @author Luca Frosini (ISTI - CNR)
  */
 @Path(Configuration.CONFIGURATIONS)

src/main/java/org/gcube/gcat/rest/administration/Group.java

@@ -28,7 +28,10 @@ import com.webcohesion.enunciate.metadata.rs.ResourceLabel;
 /**
  * This concept is mutated by Ckan which is used as underling technology to persist items.
  * 
+ * Only Catalogue-Admins or above are able to invoke non-safe methods.
+ * 
  * @author Luca Frosini (ISTI - CNR)
+ * 
  */
 @Path(Group.GROUPS)
 @ResourceGroup("Administration APIs")
@@ -73,6 +76,49 @@ public class Group extends REST<CKANGroup> implements org.gcube.gcat.api.interfa
 		return super.list(limit, offset);
 	}
 	
+	/**
+	 * 
+	 * 
+	 * A group is mainly described by the following attributes (* indicate mandatory attributes):
+	 * 
+	 * <dl>
+	 * 	
+	 * 	<dt>name* (string)</dt>
+	 * 	<dd>
+	 * 		the name of the group, a string between 2 and 100 characters long, 
+	 * 		containing only lowercase alphanumeric characters, '-' and '_' ;
+	 * 	</dd>
+	 *	
+	 *	<dt style="margin-top: 5px;">id (string)</dt>
+	 *  <dd>the id of the group;</dd>
+	 *  
+	 *	<dt style="margin-top: 5px;">title (string)</dt>
+	 *  <dd>the title of the group;</dd>
+	 *  
+	 *	<dt style="margin-top: 5px;">description (string)</dt>
+	 *  <dd>the description of the group;</dd>
+	 *  
+	 *	<dt style="margin-top: 5px;">image_url (string)</dt>
+	 *  <dd>the URL to an image to be displayed on the group’s page;</dd>
+	 * 	
+	 * 	<dt>state (string, default: 'active')</dt>
+	 * 	<dd>
+	 * 		the current state of the group, e.g. 'active' or 'deleted', 
+	 * 		only active groups show up in search results and other lists of groups, 
+	 * 		this parameter will be ignored if you are not authorized 
+	 * 		to change the state of the group;
+	 * 	</dd>
+	 *  
+	 *  <dt style="margin-top: 5px;">extras (list of dataset extra dictionaries)</dt>
+	 *  <dd>
+	 *  	the group’s extras, extras are arbitrary (key: value) metadata that can be added to groups, 
+	 *  	each extra dictionary should have keys 'key' (a string), 
+	 *  	'value' (a string), and optionally 'deleted'.
+	 *  </dd>
+	 *  
+	 * </dl>
+	 * 
+	 */
 	@POST
 	@Consumes(GCatConstants.APPLICATION_JSON_CHARSET_UTF_8)
 	@Produces(GCatConstants.APPLICATION_JSON_CHARSET_UTF_8)

src/main/java/org/gcube/gcat/rest/administration/Organization.java

@@ -28,6 +28,8 @@ import com.webcohesion.enunciate.metadata.rs.ResourceLabel;
 /**
  * This concept is mutated by Ckan which is used as underling technology to persist items.
  * 
+ * Only Catalogue-Admins or above are able to invoke non-safe methods.
+ * 
  * @author Luca Frosini (ISTI - CNR)
  */
 @Path(Organization.ORGANIZATIONS)
@@ -74,6 +76,48 @@ public class Organization extends REST<CKANOrganization>
 		return super.list(limit, offset);
 	}
 	
+	/**
+	 * An Organization is mainly described by the following attributes (* indicate mandatory attributes): 
+	 * 
+	 * <dl>
+	 * 	
+	 * 	<dt>name* (string)</dt>
+	 * 	<dd>
+	 * 		the name of the organization, a string between 2 and 100 characters long, 
+	 * 		containing only lowercase alphanumeric characters, '-' and '_' ;
+	 * 	</dd>
+	 *	
+	 *	<dt style="margin-top: 5px;">id (string)</dt>
+	 *  <dd>the id of the organization;</dd>
+	 *  
+	 *	<dt style="margin-top: 5px;">title (string)</dt>
+	 *  <dd>the title of the organization;</dd>
+	 *  
+	 *	<dt style="margin-top: 5px;">description (string)</dt>
+	 *  <dd>the description of the organization;</dd>
+	 *  
+	 *	<dt style="margin-top: 5px;">image_url (string)</dt>
+	 *  <dd>the URL to an image to be displayed on the organization's page;</dd>
+	 * 	
+	 * 	<dt>state (string, default: 'active')</dt>
+	 * 	<dd>
+	 * 		the current state of the organization, e.g. 'active' or 'deleted', 
+	 * 		only active organizations show up in search results and other lists of organizations, 
+	 * 		this parameter will be ignored if you are not authorized 
+	 * 		to change the state of the organization;
+	 * 	</dd>
+	 *  
+	 *  <dt style="margin-top: 5px;">extras (list of dataset extra dictionaries)</dt>
+	 *  <dd>
+	 *  	the organization's extras, extras are arbitrary (key: value) 
+	 *  	metadata that can be added to organizations, 
+	 *  	each extra dictionary should have keys 'key' (a string), 
+	 *  	'value' (a string), and optionally 'deleted'.
+	 *  </dd>
+	 *  
+	 * </dl>
+
+	 */
 	@POST
 	@Consumes(GCatConstants.APPLICATION_JSON_CHARSET_UTF_8)
 	@Produces(GCatConstants.APPLICATION_JSON_CHARSET_UTF_8)

src/main/java/org/gcube/gcat/rest/administration/User.java

@@ -30,6 +30,8 @@ import com.webcohesion.enunciate.metadata.rs.ResourceLabel;
 /**
  * This collection allows to interact with the catalogue users.
  * 
+ * Only Catalogue-Admins or above are able to invoke non-safe methods.
+ * 
  * @author Luca Frosini (ISTI - CNR)
  */
 @Path(User.USERS)
@@ -44,6 +46,10 @@ public class User extends REST<CKANUser> implements org.gcube.gcat.api.interface
 		super(USERS, CKAN_USER_ID_PARAMETER, CKANUser.class);
 	}
 	
+	/**
+	 * @pathExample /users
+	 * @responseExample application/json;charset=UTF-8 classpath:/api-docs-examples/user/list-user-response.json
+	 */
 	@GET
 	@Produces(GCatConstants.APPLICATION_JSON_CHARSET_UTF_8)
 //	@AuthorizationControl(allowedRoles={Role.CATALOGUE_MANAGER}, exception=NotAuthorizedException.class)
@@ -51,6 +57,38 @@ public class User extends REST<CKANUser> implements org.gcube.gcat.api.interface
 		return super.list(-1, -1);
 	}
 	
+	/**
+	 * A User is mainly described by the following attributes (* indicate mandatory attributes):
+	 * 
+	 * <dl>
+	 * 	
+	 * 	<dt>name* (string)</dt>
+	 * 	<dd>
+	 * 		the name of the user, a string between 2 and 100 characters long, 
+	 * 		containing only lowercase alphanumeric characters, '-' and '_' ;
+	 * 	</dd>
+	 *	
+	 *	<dt style="margin-top: 5px;">id (string)</dt>
+	 *  <dd>the id of the user;</dd>
+	 *  
+	 *	<dt style="margin-top: 5px;">fullname (string)</dt>
+	 *  <dd>the fullname of the user;</dd>
+	 *  
+	 *	<dt style="margin-top: 5px;">email (string)</dt>
+	 *  <dd>the email address for the user;</dd>
+	 *  
+	 *	<dt style="margin-top: 5px;">password (string)</dt>
+	 *  <dd>
+	 *  	the password of the user, a string of at least 4 characters 
+	 *  	(parameter only used internally to create a new user in Ckan);
+	 *  </dd>
+	 * 	
+	 * 	<dt style="margin-top: 5px;">about (string)</dt>
+	 *  <dd>a description of the user.</dd>
+	 *  
+	 * </dl>
+	 * 
+	 */
 	@POST
 	@Consumes(GCatConstants.APPLICATION_JSON_CHARSET_UTF_8)
 	@Produces(GCatConstants.APPLICATION_JSON_CHARSET_UTF_8)
@@ -60,6 +98,10 @@ public class User extends REST<CKANUser> implements org.gcube.gcat.api.interface
 		return super.create(json);
 	}
 	
+	/**
+	 * @pathExample /users/luca_frosini
+	 * @responseExample application/json;charset=UTF-8 classpath:/api-docs-examples/user/read-user-response.json
+	 */
 	@GET
 	@Path("/{" + CKAN_USER_ID_PARAMETER + "}")
 	@Produces(GCatConstants.APPLICATION_JSON_CHARSET_UTF_8)

src/main/resources/api-docs-examples/user/list-user-response.json

@@ -0,0 +1,32 @@
+[
+	{
+        "openid": null,
+        "about": "",
+        "display_name": "Blue Mister",
+        "name": "mister_blue",
+        "created": "2022-04-08T14:31:03.978191",
+        "email_hash": "XXXXXXX",
+        "sysadmin": false,
+        "activity_streams_email_notifications": false,
+        "state": "active",
+        "number_of_edits": 28,
+        "fullname": "Blue Mister",
+        "id": "c9f7a81d-75f6-4cf8-aab9-b4c90dce9405",
+        "number_created_packages": 0
+    },
+    {
+        "openid": null,
+        "about": "",
+        "display_name": "Brown Mister",
+        "name": "mister_brown",
+        "created": "2022-04-12T17:06:51.075728",
+        "email_hash": "XXXXXXX",
+        "sysadmin": false,
+        "activity_streams_email_notifications": false,
+        "state": "active",
+        "number_of_edits": 0,
+        "fullname": "Brown Mister",
+        "id": "7445ef41-08d8-4559-8750-3232eb0e1914",
+        "number_created_packages": 0
+    },
+]

src/main/resources/api-docs-examples/user/read-user-response.json

@@ -0,0 +1,17 @@
+{
+	"openid": null,
+	"about": "",
+	"apikey": "XXXXXXX",
+	"display_name": "Frosini Luca",
+	"name": "luca_frosini",
+	"created": "2016-12-09T15:18:21.915742",
+	"email_hash": "XXXXXXX",
+	"email": "XXXXXXX@XXXXXXX",
+	"sysadmin": false,
+	"activity_streams_email_notifications": false,
+	"state": "active",
+	"number_of_edits": 1622,
+	"fullname": "Frosini Luca",
+	"id": "aabddbb0-b761-4f30-9629-3ca2fdc08eb4",
+	"number_created_packages": 4
+}