From 150f533fc74b0994c94f777a8fc081dd2c54bee0 Mon Sep 17 00:00:00 2001 From: Luca Frosini Date: Fri, 30 Sep 2022 17:55:26 +0200 Subject: [PATCH] Improved docs --- .../rest/administration/Configuration.java | 2 + .../gcube/gcat/rest/administration/Group.java | 46 +++++++++++++++++++ .../rest/administration/Organization.java | 44 ++++++++++++++++++ .../gcube/gcat/rest/administration/User.java | 42 +++++++++++++++++ .../user/list-user-response.json | 32 +++++++++++++ .../user/read-user-response.json | 17 +++++++ 6 files changed, 183 insertions(+) create mode 100644 src/main/resources/api-docs-examples/user/list-user-response.json create mode 100644 src/main/resources/api-docs-examples/user/read-user-response.json diff --git a/src/main/java/org/gcube/gcat/rest/administration/Configuration.java b/src/main/java/org/gcube/gcat/rest/administration/Configuration.java index 7896de2..bb6d20a 100644 --- a/src/main/java/org/gcube/gcat/rest/administration/Configuration.java +++ b/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) diff --git a/src/main/java/org/gcube/gcat/rest/administration/Group.java b/src/main/java/org/gcube/gcat/rest/administration/Group.java index eb1e17b..0f50a17 100644 --- a/src/main/java/org/gcube/gcat/rest/administration/Group.java +++ b/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 implements org.gcube.gcat.api.interfa return super.list(limit, offset); } + /** + * + * + * A group is mainly described by the following attributes (* indicate mandatory attributes): + * + *
+ * + *
name* (string)
+ *
+ * the name of the group, a string between 2 and 100 characters long, + * containing only lowercase alphanumeric characters, '-' and '_' ; + *
+ * + *
id (string)
+ *
the id of the group;
+ * + *
title (string)
+ *
the title of the group;
+ * + *
description (string)
+ *
the description of the group;
+ * + *
image_url (string)
+ *
the URL to an image to be displayed on the group’s page;
+ * + *
state (string, default: 'active')
+ *
+ * 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; + *
+ * + *
extras (list of dataset extra dictionaries)
+ *
+ * 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'. + *
+ * + *
+ * + */ @POST @Consumes(GCatConstants.APPLICATION_JSON_CHARSET_UTF_8) @Produces(GCatConstants.APPLICATION_JSON_CHARSET_UTF_8) diff --git a/src/main/java/org/gcube/gcat/rest/administration/Organization.java b/src/main/java/org/gcube/gcat/rest/administration/Organization.java index 9727a42..14e16ab 100644 --- a/src/main/java/org/gcube/gcat/rest/administration/Organization.java +++ b/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 return super.list(limit, offset); } + /** + * An Organization is mainly described by the following attributes (* indicate mandatory attributes): + * + *
+ * + *
name* (string)
+ *
+ * the name of the organization, a string between 2 and 100 characters long, + * containing only lowercase alphanumeric characters, '-' and '_' ; + *
+ * + *
id (string)
+ *
the id of the organization;
+ * + *
title (string)
+ *
the title of the organization;
+ * + *
description (string)
+ *
the description of the organization;
+ * + *
image_url (string)
+ *
the URL to an image to be displayed on the organization's page;
+ * + *
state (string, default: 'active')
+ *
+ * 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; + *
+ * + *
extras (list of dataset extra dictionaries)
+ *
+ * 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'. + *
+ * + *
+ + */ @POST @Consumes(GCatConstants.APPLICATION_JSON_CHARSET_UTF_8) @Produces(GCatConstants.APPLICATION_JSON_CHARSET_UTF_8) diff --git a/src/main/java/org/gcube/gcat/rest/administration/User.java b/src/main/java/org/gcube/gcat/rest/administration/User.java index 0fb9bd3..f00e46d 100644 --- a/src/main/java/org/gcube/gcat/rest/administration/User.java +++ b/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 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 implements org.gcube.gcat.api.interface return super.list(-1, -1); } + /** + * A User is mainly described by the following attributes (* indicate mandatory attributes): + * + *
+ * + *
name* (string)
+ *
+ * the name of the user, a string between 2 and 100 characters long, + * containing only lowercase alphanumeric characters, '-' and '_' ; + *
+ * + *
id (string)
+ *
the id of the user;
+ * + *
fullname (string)
+ *
the fullname of the user;
+ * + *
email (string)
+ *
the email address for the user;
+ * + *
password (string)
+ *
+ * the password of the user, a string of at least 4 characters + * (parameter only used internally to create a new user in Ckan); + *
+ * + *
about (string)
+ *
a description of the user.
+ * + *
+ * + */ @POST @Consumes(GCatConstants.APPLICATION_JSON_CHARSET_UTF_8) @Produces(GCatConstants.APPLICATION_JSON_CHARSET_UTF_8) @@ -60,6 +98,10 @@ public class User extends REST 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) diff --git a/src/main/resources/api-docs-examples/user/list-user-response.json b/src/main/resources/api-docs-examples/user/list-user-response.json new file mode 100644 index 0000000..a4e6515 --- /dev/null +++ b/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 + }, +] \ No newline at end of file diff --git a/src/main/resources/api-docs-examples/user/read-user-response.json b/src/main/resources/api-docs-examples/user/read-user-response.json new file mode 100644 index 0000000..92b620b --- /dev/null +++ b/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 +} \ No newline at end of file