Improving documentation

This commit is contained in:
Luca Frosini 2022-09-30 13:55:59 +02:00
parent 3c9e14c945
commit 816effa271
8 changed files with 85 additions and 8 deletions

View File

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

View File

@ -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. * @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. * If the results are too much the operation could fail.
* It is recommended to request no more than 1000 results. * 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. * @return It returns an array list of string containing the ids (i.e. names) of the items.
* E.g.<pre>["item0","items1",...,"item10"]</pre> * E.g.<pre>["item0","items1",...,"item10"]</pre>
* *

View File

@ -35,9 +35,10 @@ import com.webcohesion.enunciate.metadata.rs.ResourceGroup;
import com.webcohesion.enunciate.metadata.rs.ResourceLabel; 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) * @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 @GET
@Produces(MediaType.APPLICATION_JSON) @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); setCalledMethod("GET /" + PROFILES);
try { try {
ISProfile isProfile = new ISProfile(); ISProfile isProfile = new ISProfile();
if(countOnly) { if(count) {
return createCountJson(isProfile.count()); return createCountJson(isProfile.count());
}else{ }else{
ArrayNode arrayNode = isProfile.list(); 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; 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 @GET
@Path("/{" + PROFILE_NAME_PARAMETER + "}") @Path("/{" + PROFILE_NAME_PARAMETER + "}")
@Consumes({MediaType.APPLICATION_XML, GCatConstants.APPLICATION_JSON_CHARSET_UTF_8})
@Produces({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, public String read(@PathParam(PROFILE_NAME_PARAMETER) String name,
@DefaultValue(MediaType.APPLICATION_XML) @HeaderParam("Accept") String accept) { @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(); ISProfile isProfile = new ISProfile();
boolean xml = false; boolean xml = true;
if(accept.startsWith(MediaType.APPLICATION_XML)) { if(accept.startsWith(MediaType.APPLICATION_JSON)) {
xml = true; xml = false;
} }
return isProfile.read(name, xml); return isProfile.read(name, xml);
} catch(WebApplicationException e) { } catch(WebApplicationException e) {

View File

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

View File

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

View File

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

View File

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

View File

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