From e22cbcc0f5cd9fef62195a9fa2f7eb0359425404 Mon Sep 17 00:00:00 2001 From: Luca Frosini Date: Tue, 27 Sep 2022 15:01:11 +0200 Subject: [PATCH] improving documentation --- src/main/java/org/gcube/gcat/rest/Item.java | 32 ++++++++++-- src/main/resources/create-item-request.json | 24 +++++++++ src/main/resources/create-item-response.json | 55 ++++++++++++++++++++ src/main/resources/read-item-response.json | 55 ++++++++++++++++++++ 4 files changed, 163 insertions(+), 3 deletions(-) create mode 100644 src/main/resources/create-item-request.json create mode 100644 src/main/resources/create-item-response.json create mode 100644 src/main/resources/read-item-response.json diff --git a/src/main/java/org/gcube/gcat/rest/Item.java b/src/main/java/org/gcube/gcat/rest/Item.java index 65a40f5..fc33fd0 100644 --- a/src/main/java/org/gcube/gcat/rest/Item.java +++ b/src/main/java/org/gcube/gcat/rest/Item.java @@ -61,7 +61,8 @@ public class Item extends REST implements org.gcube.gcat.api.interf *
* Optional.Default:false.
* If True, private datasets will be included in the results.
- * Only private datasets from the user’s organizations will be returned. For the sysadmins will be returned all private datasets.
+ * Only private datasets from the user’s organizations will be returned. + * For the sysadmins will be returned all private datasets.
* E.g. /items?include_private=true *
* @@ -205,6 +206,9 @@ public class Item extends REST implements org.gcube.gcat.api.interf * } * * ] + * + * @pathExample /items?limit=10&offset=0 + * @responseExample application/json;charset=UTF-8 ["item0","items1",...,"item10"] */ @GET @Produces(GCatConstants.APPLICATION_JSON_CHARSET_UTF_8) @@ -376,7 +380,12 @@ public class Item extends REST implements org.gcube.gcat.api.interf * * @param json containing the item to be created * @return 201 Created HTTP Status to indicate that the item has been created. - * Some operation could continue in background such as the social post creation. + * 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 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 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 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 implements org.gcube.gcat.api.interf * purge API using the PURGE HTTP Method. *

* - * @param purge Default:false) it completely removes all the items in the default CKAN organization. + * @param purge (Default:false) it completely removes all the items in the default CKAN organization. * @return 202 Accepted 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 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 implements org.gcube.gcat.api.interf * @return 202 Accepted HTTP Status to indicate that the request has been * properly taken in charge.
* The operation will continue in background. + * + * @pathExample /items/my_test_item + * */ @POST @Path("/{" + ITEM_ID_PARAMETER + "}") diff --git a/src/main/resources/create-item-request.json b/src/main/resources/create-item-request.json new file mode 100644 index 0000000..8943749 --- /dev/null +++ b/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" + } + ] +} \ No newline at end of file diff --git a/src/main/resources/create-item-response.json b/src/main/resources/create-item-response.json new file mode 100644 index 0000000..12dc3b7 --- /dev/null +++ b/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" +} \ No newline at end of file diff --git a/src/main/resources/read-item-response.json b/src/main/resources/read-item-response.json new file mode 100644 index 0000000..12dc3b7 --- /dev/null +++ b/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" +} \ No newline at end of file