From 8395cebf3c3a9e89ba915f9597e24a479048bd6a Mon Sep 17 00:00:00 2001
From: Luca Frosini <luca.frosini@isti.cnr.it>
Date: Mon, 11 Apr 2022 15:39:11 +0200
Subject: [PATCH] Adding docs

---
 .../org/gcube/gcat/rest/Configuration.java    | 68 ++++++++++++++++++-
 1 file changed, 65 insertions(+), 3 deletions(-)

diff --git a/src/main/java/org/gcube/gcat/rest/Configuration.java b/src/main/java/org/gcube/gcat/rest/Configuration.java
index f2a122d..4d8c50c 100644
--- a/src/main/java/org/gcube/gcat/rest/Configuration.java
+++ b/src/main/java/org/gcube/gcat/rest/Configuration.java
@@ -101,10 +101,42 @@ public class Configuration extends BaseREST implements org.gcube.gcat.api.interf
 	@Override
 	@AuthorizationControl(allowedRoles={Role.CATALOGUE_MANAGER}, exception=NotAuthorizedException.class)
 	@StatusCodes ({
-		@ResponseCode(code = 200, condition = "Object successfully created"),
-		@ResponseCode(code = 401, condition = "Only Catalogue-Managers can invoke such a method"),
-		@ResponseCode(code = 500, condition = "Error while persisting configuration on the information system"),
+		@ResponseCode(code = 201, condition = "Catalogue configuration successfully created."),
+		@ResponseCode(code = 401, condition = "Only Catalogue-Managers can create catalogue configuration."),
+		@ResponseCode(code = 500, condition = "Error while persisting catalogue configuration."),
 	})
+	/**
+	 * Creates the catalogue configuration for the current context using the json provided as parameter
+	 * @param json the configuration representation
+	 * 
+	 *	{
+	 *		"id": "584b8503-a490-4a89-8372-e21830fa716c",
+	 *		"context": "/gcube/devsec/devVRE",
+	 *		"defaultOrganization": "devvre",
+	 *		"supportedOrganizations": [ "devvre" ],
+	 *		"ckanURL": "https://ckan-d-d4s.d4science.org",
+	 *		"solrURL": "https://ckan-d-d4s.d4science.org/solr/",
+	 *		"socialPostEnabled": false,
+	 *		"notificationToUsersEnabled": true,
+	 *		"moderationEnabled": true
+	 *	}
+	 * 
+	 * @return the created configuration
+	 * 
+	 * 	{
+	 *		"id": "584b8503-a490-4a89-8372-e21830fa716c",
+	 *		"context": "/gcube/devsec/devVRE",
+	 *		"defaultOrganization": "devvre",
+	 *		"supportedOrganizations": [ "devvre" ],
+	 *		"ckanURL": "https://ckan-d-d4s.d4science.org",
+	 *		"solrURL": "https://ckan-d-d4s.d4science.org/solr/",
+	 *		"socialPostEnabled": false,
+	 *		"notificationToUsersEnabled": true,
+	 *		"moderationEnabled": true
+	 *	}
+	 *  
+	 * @throws WebServiceException
+	 */
 	public Response create(String json) throws WebServiceException {
 		try {
 			ServiceCatalogueConfiguration catalogueConfiguration = ServiceCatalogueConfiguration.getServiceCatalogueConfiguration(json);
@@ -126,6 +158,16 @@ public class Configuration extends BaseREST implements org.gcube.gcat.api.interf
 	@Path("/{" + CONTEXT_FULLNAME_PARAMETER + "}")
 	@Produces(GCatConstants.APPLICATION_JSON_CHARSET_UTF_8)
 	@AuthorizationControl(allowedRoles={Role.CATALOGUE_EDITOR, Role.CATALOGUE_ADMIN, Role.CATALOGUE_MANAGER}, exception=NotAuthorizedException.class)
+	@StatusCodes ({
+		@ResponseCode(code = 200, condition = "Catalogue configuration successfully read."),
+		@ResponseCode(code = 401, condition = "Only User with role Catalogue-Editors or above can read a catalogue configuration."),
+		@ResponseCode(code = 500, condition = "Error while reading catalogue configuration."),
+	})
+	/**
+	 * @param context
+	 * @return
+	 * @throws WebServiceException
+	 */
 	public Response read(@PathParam(CONTEXT_FULLNAME_PARAMETER) String context) throws WebServiceException {
 		try {
 			checkContext(context);
@@ -160,6 +202,11 @@ public class Configuration extends BaseREST implements org.gcube.gcat.api.interf
 	@Consumes(GCatConstants.APPLICATION_JSON_CHARSET_UTF_8)
 	@Produces(GCatConstants.APPLICATION_JSON_CHARSET_UTF_8)
 	@AuthorizationControl(allowedRoles={Role.CATALOGUE_MANAGER}, exception=NotAuthorizedException.class)
+	@StatusCodes ({
+		@ResponseCode(code = 200, condition = "Catalogue configuration successfully created/updated."),
+		@ResponseCode(code = 401, condition = "Only Catalogue-Managers can create/update catalogue configuration."),
+		@ResponseCode(code = 500, condition = "Error while creating/updating catalogue configuration."),
+	})
 	public String createOrUpdate(@PathParam(CONTEXT_FULLNAME_PARAMETER) String context, String json) throws WebServiceException {
 		try {
 			ServiceCatalogueConfiguration catalogueConfiguration = ServiceCatalogueConfiguration.getServiceCatalogueConfiguration(json);
@@ -197,6 +244,11 @@ public class Configuration extends BaseREST implements org.gcube.gcat.api.interf
 	@Consumes(GCatConstants.APPLICATION_JSON_CHARSET_UTF_8)
 	@Produces(GCatConstants.APPLICATION_JSON_CHARSET_UTF_8)
 	@AuthorizationControl(allowedRoles={Role.CATALOGUE_MANAGER}, exception=NotAuthorizedException.class)
+	@StatusCodes ({
+		@ResponseCode(code = 200, condition = "Catalogue configuration successfully updated."),
+		@ResponseCode(code = 401, condition = "Only Catalogue-Managers can update catalogue configuration."),
+		@ResponseCode(code = 500, condition = "Error while updating catalogue configuration."),
+	})
 	public Response patch(@PathParam(CONTEXT_FULLNAME_PARAMETER) String context, String json) throws WebServiceException {
 		try {
 			checkContext(context);
@@ -251,6 +303,11 @@ public class Configuration extends BaseREST implements org.gcube.gcat.api.interf
 	@DELETE
 	@Path("/{" + CONTEXT_FULLNAME_PARAMETER + "}")
 	@AuthorizationControl(allowedRoles={Role.CATALOGUE_MANAGER}, exception=NotAuthorizedException.class)
+	@StatusCodes ({
+		@ResponseCode(code = 200, condition = "Catalogue configuration successfully deleted."),
+		@ResponseCode(code = 401, condition = "Only Catalogue-Managers can delete catalogue configuration."),
+		@ResponseCode(code = 500, condition = "Error while deleting catalogue configuration."),
+	})
 	public Response delete(@PathParam(CONTEXT_FULLNAME_PARAMETER) String context, 
 			@QueryParam(GCatConstants.PURGE_QUERY_PARAMETER) @DefaultValue("false") Boolean purge) throws WebServiceException {
 		try {
@@ -283,6 +340,11 @@ public class Configuration extends BaseREST implements org.gcube.gcat.api.interf
 	@PURGE
 	@Path("/{" + CONTEXT_FULLNAME_PARAMETER + "}")
 	@AuthorizationControl(allowedRoles={Role.CATALOGUE_MANAGER}, exception=NotAuthorizedException.class)
+	@StatusCodes ({
+		@ResponseCode(code = 200, condition = "Catalogue configuration successfully deleted."),
+		@ResponseCode(code = 401, condition = "Only Catalogue-Managers can delete catalogue configuration."),
+		@ResponseCode(code = 500, condition = "Error while deleting catalogue configuration."),
+	})
 	public Response purge(@PathParam(CONTEXT_FULLNAME_PARAMETER) String context) throws WebServiceException {
 		try {
 			checkContext(context);