improving documentation

src/main/java/org/gcube/gcat/rest/Item.java

@@ -61,7 +61,8 @@ public class Item extends REST<CKANPackage> implements org.gcube.gcat.api.interf
 	 * 	<dd>
 	 * 		<em>Optional</em>.<em>Default:false</em>.<br/>
 	 * 		If True, private datasets will be included in the results.<br/>
-	 * 		Only private datasets from the user’s organizations will be returned. For the sysadmins will be returned all private datasets.<br/>
+	 * 		Only private datasets from the user’s organizations will be returned. 
+	 * 		For the sysadmins will be returned all private datasets.<br/>
 	 * 		E.g. <code>/items?include_private=true</code>
 	 * 	</dd>
 	 * 	
@@ -205,6 +206,9 @@ public class Item extends REST<CKANPackage> implements org.gcube.gcat.api.interf
 	 *  	}
 	 *  
 	 *  ]</pre>
+	 *  
+	 *  @pathExample /items?limit=10&offset=0
+	 *  @responseExample application/json;charset=UTF-8 ["item0","items1",...,"item10"]
 	 */
 	@GET
 	@Produces(GCatConstants.APPLICATION_JSON_CHARSET_UTF_8)
@@ -377,6 +381,11 @@ public class Item extends REST<CKANPackage> implements org.gcube.gcat.api.interf
 	 * @param json containing the item to be created
 	 * @return <code>201 Created</code> HTTP Status to indicate that the item has been created.
 	 * 	Some operation could continue in background such as the social post creation.
+	 * 
+	 * @pathExample /items?social_post=true
+	 * @requestExample application/json;charset=UTF-8 classpath:/create-item-request.json
+	 * @responseExample application/json;charset=UTF-8 classpath:/create-item-response.json
+	 * 
 	 */
 	@POST
 	@Consumes(GCatConstants.APPLICATION_JSON_CHARSET_UTF_8)
@@ -387,6 +396,10 @@ public class Item extends REST<CKANPackage> implements org.gcube.gcat.api.interf
 		return super.create(json);
 	}
 	
+	/**
+	 * @pathExample /items/my_test_item
+	 * @responseExample application/json;charset=UTF-8 classpath:/read-item-response.json
+	 */
 	@GET
 	@Path("/{" + ITEM_ID_PARAMETER + "}")
 	@Produces(GCatConstants.APPLICATION_JSON_CHARSET_UTF_8)
@@ -418,6 +431,9 @@ public class Item extends REST<CKANPackage> implements org.gcube.gcat.api.interf
 		return super.patch(id, json);
 	}
 	
+	/**
+	 * @pathExample /items/my_test_item
+	 */
 	@DELETE
 	@Path("/{" + ITEM_ID_PARAMETER + "}")
 	@Override
@@ -427,6 +443,9 @@ public class Item extends REST<CKANPackage> implements org.gcube.gcat.api.interf
 		return super.delete(id, purge);
 	}
 	
+	/**
+	 * @pathExample /items/my_test_item
+	 */
 	@PURGE
 	@Path("/{" + ITEM_ID_PARAMETER + "}")
 	@Override
@@ -487,10 +506,12 @@ public class Item extends REST<CKANPackage> implements org.gcube.gcat.api.interf
 	 * 	purge API using the <code>PURGE</code> HTTP Method.
 	 * </p>
 	 * 
-	 * @param purge <em>Default:false</em>) it completely removes all the items in the default CKAN organization.
+	 * @param purge <em>(Default:false)</em> it completely removes all the items in the default CKAN organization.
 	 * @return <code>202 Accepted</code> HTTP Status to indicate that the request has been properly take in charge.
 	 * 	The operation will continue in background.
 	 * @throws WebServiceException if an error occurs.
+	 * 
+	 * @pathExample /items?purge=false
 	 */
 	@DELETE
 	@Produces(GCatConstants.APPLICATION_JSON_CHARSET_UTF_8)
@@ -535,6 +556,8 @@ public class Item extends REST<CKANPackage> implements org.gcube.gcat.api.interf
 	 * 	The operation will continue in background.
 	 * 
 	 * @throws WebServiceException if an error occurs.
+	 * 
+	 * @pathExample /items
 	 */
 	@PURGE
 	@Produces(GCatConstants.APPLICATION_JSON_CHARSET_UTF_8)
@@ -575,6 +598,9 @@ public class Item extends REST<CKANPackage> implements org.gcube.gcat.api.interf
 	 * @return <code>202 Accepted</code> HTTP Status to indicate that the request has been 
 	 * 	properly taken in charge.<br />
 	 * 	The operation will continue in background.
+	 * 
+	 * @pathExample /items/my_test_item
+	 * 
 	 */
 	@POST
 	@Path("/{" + ITEM_ID_PARAMETER + "}")

src/main/resources/create-item-request.json

@@ -0,0 +1,24 @@
+{
+    "name": "my_test_item",
+    "title": "My Test Item",
+    "license_id": "CC-BY-SA-4.0",
+    "private": false,
+    "notes": "A test item of Luca Frosini",
+    "url": "http://www.d4science.org",
+    "tags": [
+        {
+            "name": "Test"
+        }
+    ],
+    "resources": [],
+    "extras": [
+        {
+            "key": "Language",
+            "value": "EN"
+        },
+        {
+            "key": "system:type",
+            "value": "EmptyProfile"
+        }
+    ]
+}

src/main/resources/create-item-response.json

@@ -0,0 +1,55 @@
+{
+    "rating": 0.0,
+    "license_title": "Creative Commons Attribution Share-Alike 4.0",
+    "maintainer": "Frosini Luca",
+    "relationships_as_object": [],
+    "private": false,
+    "maintainer_email": "luca.frosini@isti.cnr.it",
+    "num_tags": 1,
+    "id": "09db787f-d673-4c99-985f-dd16103332ad",
+    "metadata_created": "2022-09-27T12:53:10.312673",
+    "metadata_modified": "2022-09-27T12:53:10.312680",
+    "author": "Frosini Luca",
+    "author_email": "luca.frosini@isti.cnr.it",
+    "state": "active",
+    "version": null,
+    "creator_user_id": "287b2eec-4cd7-4e50-817f-e6dce19995c7",
+    "type": "dataset",
+    "resources": [],
+    "num_resources": 0,
+    "tags": [
+        {
+            "vocabulary_id": null,
+            "state": "active",
+            "display_name": "Test",
+            "id": "78f1cb4b-dfe8-43e4-af0d-e874034a1316",
+            "name": "Test"
+        }
+    ],
+    "groups": [],
+    "license_id": "CC-BY-SA-4.0",
+    "relationships_as_subject": [],
+    "organization": { ... },
+    "name": "my_test_item",
+    "isopen": true,
+    "url": "http://www.d4science.org",
+    "notes": "A test item of Luca Frosini",
+    "extras": [
+        {
+            "key": "Item URL",
+            "value": "https://.....d4science.org/ctlg/...../my_test_item"
+        },
+        {
+            "key": "Language",
+            "value": "EN"
+        },
+        {
+            "key": "system:type",
+            "value": "EmptyProfile"
+        }
+    ],
+    "license_url": "https://creativecommons.org/licenses/by-sa/4.0/",
+    "ratings_count": 0,
+    "title": "My Test Item",
+    "revision_id": "939e1d97-f497-4ab5-86ed-d6d9c3ec7604"
+}

src/main/resources/read-item-response.json

@@ -0,0 +1,55 @@
+{
+    "rating": 0.0,
+    "license_title": "Creative Commons Attribution Share-Alike 4.0",
+    "maintainer": "Frosini Luca",
+    "relationships_as_object": [],
+    "private": false,
+    "maintainer_email": "luca.frosini@isti.cnr.it",
+    "num_tags": 1,
+    "id": "09db787f-d673-4c99-985f-dd16103332ad",
+    "metadata_created": "2022-09-27T12:53:10.312673",
+    "metadata_modified": "2022-09-27T12:53:10.312680",
+    "author": "Frosini Luca",
+    "author_email": "luca.frosini@isti.cnr.it",
+    "state": "active",
+    "version": null,
+    "creator_user_id": "287b2eec-4cd7-4e50-817f-e6dce19995c7",
+    "type": "dataset",
+    "resources": [],
+    "num_resources": 0,
+    "tags": [
+        {
+            "vocabulary_id": null,
+            "state": "active",
+            "display_name": "Test",
+            "id": "78f1cb4b-dfe8-43e4-af0d-e874034a1316",
+            "name": "Test"
+        }
+    ],
+    "groups": [],
+    "license_id": "CC-BY-SA-4.0",
+    "relationships_as_subject": [],
+    "organization": { ... },
+    "name": "my_test_item",
+    "isopen": true,
+    "url": "http://www.d4science.org",
+    "notes": "A test item of Luca Frosini",
+    "extras": [
+        {
+            "key": "Item URL",
+            "value": "https://.....d4science.org/ctlg/...../my_test_item"
+        },
+        {
+            "key": "Language",
+            "value": "EN"
+        },
+        {
+            "key": "system:type",
+            "value": "EmptyProfile"
+        }
+    ],
+    "license_url": "https://creativecommons.org/licenses/by-sa/4.0/",
+    "ratings_count": 0,
+    "title": "My Test Item",
+    "revision_id": "939e1d97-f497-4ab5-86ed-d6d9c3ec7604"
+}