gCubeSystem
/
gcat
15
0
Fork 0
Code Issues Pull Requests Releases 13 Wiki Activity

Improved docs

This commit is contained in:
Luca Frosini 2022-09-30 17:55:26 +02:00
parent 73e7f67d7d
commit 150f533fc7
6 changed files with 183 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
src/main/java/org/gcube/gcat/rest/administration/Configuration.java
View File

@ -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)

46
src/main/java/org/gcube/gcat/rest/administration/Group.java
View File

@ -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)

44
src/main/java/org/gcube/gcat/rest/administration/Organization.java
View File

@ -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)

42
src/main/java/org/gcube/gcat/rest/administration/User.java
View File

@ -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)

32
src/main/resources/api-docs-examples/user/list-user-response.json Normal file
View File

@ -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
},
]

17
src/main/resources/api-docs-examples/user/read-user-response.json Normal file
View File

@ -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
}