Improving documentation

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

@@ -1,6 +1,7 @@
 package org.gcube.gcat.rest;
 
 import javax.ws.rs.core.Context;
+import javax.ws.rs.core.HttpHeaders;
 import javax.ws.rs.core.Response.ResponseBuilder;
 import javax.ws.rs.core.UriInfo;
 
@@ -22,6 +23,9 @@ public class BaseREST {
 	
 	private final Logger logger = LoggerFactory.getLogger(this.getClass());
 	
+	@Context
+	protected HttpHeaders headers;
+	
 	@Context
 	protected UriInfo uriInfo;
 	

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

@@ -300,7 +300,7 @@ public class Item extends REST<CKANPackage> implements org.gcube.gcat.api.interf
 	 * @param limit (<em>Default:10</em>) To get unlimited results the limit query parameters must be set to -1. 
 	 * 	If the results are too much the operation could fail. 
 	 * 	It is recommended to request no more than 1000 results. 
-	 * @param offset <em>Default:0</em>) The offset parameter indicates the starting position of the result.
+	 * @param offset (<em>Default:0</em>) The offset parameter indicates the starting position of the result.
 	 * @return It returns an array list of string containing the ids (i.e. names) of the items.
 	 * 	E.g.<pre>["item0","items1",...,"item10"]</pre>
 	 * 	

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

@@ -35,9 +35,10 @@ import com.webcohesion.enunciate.metadata.rs.ResourceGroup;
 import com.webcohesion.enunciate.metadata.rs.ResourceLabel;
 
 /**
- * At creation and update time the provided profile is validated against the defined XSD schema.
+ * A Profile must comply with the defined <a href="../profiles/SCHEMA">XSD schema</a> .
  * 
- * <a href="https://wiki.gcube-system.org/gcube/GCat_Background#Metadata_Profile_v.4"></>
+ *  Please find the documentation of profile schema at:
+ * at <a href="https://wiki.gcube-system.org/gcube/GCat_Background#Metadata_Profile_v.4">Metadata Profile</>
  * 
  * @author Luca Frosini (ISTI - CNR)
  */
@@ -81,13 +82,28 @@ public class Profile extends BaseREST implements org.gcube.gcat.api.interfaces.P
 		}
 	}
 	
+	/**
+	 * Returns the list of profiles name available for the 
+	 * context of the request 
+	 * (i.e. the context where the token has been generated).
+	 * 
+	 * @param count (<em>Default:false</em>) If <code>count=true</code> the API returns total number of profile instead of the list.
+	 * @return a JSON Array. 
+	 * 
+	 * @pathExample /profiles
+	 * @responseExample application/json;charset=UTF-8 ["EmptyProfile","TestProfile",...,"ComplexProfile"]
+	 * 
+	 * @pathExample /profiles?count=true
+	 * @responseExample application/json;charset=UTF-8 {"count":5}
+	 * 
+	 */
 	@GET
 	@Produces(MediaType.APPLICATION_JSON)
-	public String listOrCount(@QueryParam(GCatConstants.COUNT_QUERY_PARAMETER) @DefaultValue("false") Boolean countOnly) {
+	public String listOrCount(@QueryParam(GCatConstants.COUNT_QUERY_PARAMETER) @DefaultValue("false") Boolean count) {
 		setCalledMethod("GET /" + PROFILES);
 		try {
 			ISProfile isProfile = new ISProfile();
-			if(countOnly) {
+			if(count) {
 				return createCountJson(isProfile.count());
 			}else{
 				ArrayNode arrayNode = isProfile.list();
@@ -118,8 +134,29 @@ public class Profile extends BaseREST implements org.gcube.gcat.api.interfaces.P
 	
 	public static int PRETTY_PRINT_INDENT_FACTOR = 4;
 	
+	/**
+	 * This API allow to read a profile definition.<br/>
+	 * 
+	 * @param accept This API return by default the content in XML.
+	 * 	<p>
+	 * 		It is possible reading a profile in JSON by specifing the HTTP Header:<br/>
+	 * 		<code>Accept: application/json</code>
+	 *	</p> 
+	 * @param name the name of the profile
+	 * @return the profile definition
+	 * 
+	 * @pathExample /profiles/EmptyProfile
+	 * @requestExample application/json;charset=UTF-8
+	 * @responseExample application/json;charset=UTF-8 classpath:/api-docs-examples/profile/read-profile-response.json
+	 * 
+	 * @pathExample /profiles/EmptyProfile
+	 * @requestExample application/xml
+	 * @responseExample application/xml classpath:/api-docs-examples/profile/read-profile-response.xml
+	 *   
+	 */
 	@GET
 	@Path("/{" + PROFILE_NAME_PARAMETER + "}")
+	@Consumes({MediaType.APPLICATION_XML, GCatConstants.APPLICATION_JSON_CHARSET_UTF_8})
 	@Produces({MediaType.APPLICATION_XML, GCatConstants.APPLICATION_JSON_CHARSET_UTF_8})
 	public String read(@PathParam(PROFILE_NAME_PARAMETER) String name,
 			@DefaultValue(MediaType.APPLICATION_XML) @HeaderParam("Accept") String accept) {
@@ -131,9 +168,9 @@ public class Profile extends BaseREST implements org.gcube.gcat.api.interfaces.P
 			}
 			
 			ISProfile isProfile = new ISProfile();
-			boolean xml = false;
-			if(accept.startsWith(MediaType.APPLICATION_XML)) {
-				xml = true;
+			boolean xml = true;
+			if(accept.startsWith(MediaType.APPLICATION_JSON)) {
+				xml = false;
 			}
 			return isProfile.read(name, xml);
 		} catch(WebApplicationException e) {

src/main/java/org/gcube/gcat/rest/administration/Configuration.java

@@ -49,6 +49,7 @@ import com.webcohesion.enunciate.metadata.swagger.OperationId;
  * A Configuration is described by the following attributes: 
  *	
  * <dl>
+ * 	
  * 	<dt>context (string)</dt>
  * 	<dd>it must contains the same value of requesting context;</dd>
  *	

src/main/resources/api-docs-examples/profile/create-profile-request.xml

@@ -0,0 +1,8 @@
+<metadataformat type="EmptyProfile">
+	<metadatafield>
+		<fieldName>test</fieldName>
+		<mandatory>false</mandatory>
+		<dataType>String</dataType>
+		<note>Test field</note>
+	</metadatafield>
+</metadataformat>

src/main/resources/api-docs-examples/profile/create-profile-response.xml

@@ -0,0 +1,8 @@
+<metadataformat type="EmptyProfile">
+	<metadatafield>
+		<fieldName>test</fieldName>
+		<mandatory>false</mandatory>
+		<dataType>String</dataType>
+		<note>Test field</note>
+	</metadatafield>
+</metadataformat>

src/main/resources/api-docs-examples/profile/read-profile-response.json

@@ -0,0 +1,11 @@
+{
+	"metadataformat": {
+		"metadatafield": {
+			"note": "Test field",
+			"fieldName": "test",
+			"dataType": "String",
+			"mandatory": false
+		},
+		"type": "EmptyProfile"
+	}
+}

src/main/resources/api-docs-examples/profile/read-profile-response.xml

@@ -0,0 +1,8 @@
+<metadataformat type="EmptyProfile">
+	<metadatafield>
+		<fieldName>test</fieldName>
+		<mandatory>false</mandatory>
+		<dataType>String</dataType>
+		<note>Test field</note>
+	</metadatafield>
+</metadataformat>