diff --git a/src/main/java/org/gcube/grsf/publisher/rest/FisheryRESTAPIs.java b/src/main/java/org/gcube/grsf/publisher/rest/FisheryRESTAPIs.java
index 1efd4d5..2405c40 100644
--- a/src/main/java/org/gcube/grsf/publisher/rest/FisheryRESTAPIs.java
+++ b/src/main/java/org/gcube/grsf/publisher/rest/FisheryRESTAPIs.java
@@ -17,7 +17,6 @@ import org.gcube.grsf.publisher.annotation.PATCH;
import org.gcube.grsf.publisher.annotation.PURGE;
import org.gcube.grsf.publisher.ckan.record.FisheryRecord;
-import com.webcohesion.enunciate.metadata.Label;
import com.webcohesion.enunciate.metadata.rs.ResourceGroup;
import com.webcohesion.enunciate.metadata.rs.ResourceLabel;
import com.webcohesion.enunciate.metadata.rs.ResponseCode;
@@ -41,7 +40,7 @@ public class FisheryRESTAPIs extends BaseRESTAPIs {
/**
*
* The listing API provides paginated results by using the query parameters limit and offset.
- * It returns an array list of string containing the GRSF UUIDs of the records.
+ * It returns an array list of string containing the GRSF UUIDs of the fishery records.
* Each name can be used as {fishery_record_id}
path parameter to manage such a record.
*
*
@@ -184,7 +183,11 @@ public class FisheryRESTAPIs extends BaseRESTAPIs {
}
/**
+ * This API allows to create a fishery record
* @pathExample /fishery
+ *
+ * @requestExample application/json;charset=UTF-8 classpath:/api-docs-examples/fishery/create-fishery-request.json
+ * @responseExample application/json;charset=UTF-8 classpath:/api-docs-examples/fishery/create-fishery-response.json
*/
@POST
@Consumes(GCatConstants.APPLICATION_JSON_CHARSET_UTF_8)
@@ -197,7 +200,9 @@ public class FisheryRESTAPIs extends BaseRESTAPIs {
}
/**
- * @pathExample /fishery/bc26e8d0-6ab3-4547-9922-d40407fc5dbd
+ * This API allows to read a fishery record
+ * @pathExample /fishery/d0145931-58d3-4561-bf64-363b61df016b
+ * @responseExample application/json;charset=UTF-8 classpath:/api-docs-examples/fishery/read-fishery-response.json
*/
@GET
@Path("/{" + GRSF_RECORD_UUID_PARAMETER + "}")
@@ -211,7 +216,10 @@ public class FisheryRESTAPIs extends BaseRESTAPIs {
}
/**
- * @pathExample /fishery/bc26e8d0-6ab3-4547-9922-d40407fc5dbd
+ * This API allows to update a fishery record
+ * @pathExample /fishery/d0145931-58d3-4561-bf64-363b61df016b
+ * @requestExample application/json;charset=UTF-8 classpath:/api-docs-examples/fishery/create-fishery-request.json
+ * @responseExample application/json;charset=UTF-8 classpath:/api-docs-examples/fishery/create-fishery-response.json
*/
@PUT
@Path("/{" + GRSF_RECORD_UUID_PARAMETER + "}")
@@ -226,7 +234,13 @@ public class FisheryRESTAPIs extends BaseRESTAPIs {
}
/**
- * @pathExample /fishery/bc26e8d0-6ab3-4547-9922-d40407fc5dbd
+ * This API allows to patch a fishery record.
+ * The service only updates the provided properties and,
+ * eventually, creates resources (e.g., time series) and
+ * adds tags or groups to the records.
+ * The API does not guarantee that the record is removed from an
+ * old group/tag associated due to the old property value.
+ * @pathExample /fishery/d0145931-58d3-4561-bf64-363b61df016b
*/
@PATCH
@Path("/{" + GRSF_RECORD_UUID_PARAMETER + "}")
@@ -241,7 +255,12 @@ public class FisheryRESTAPIs extends BaseRESTAPIs {
}
/**
- * @pathExample /fishery/bc26e8d0-6ab3-4547-9922-d40407fc5dbd
+ * This API allows to delete/purge (when the purge query parameter is true)
+ * a fishery record.
+ * In case of delete, the fishery record is no longer visible,
+ * but it still exists and can be restored.
+ * In case of purge, the record is completely deleted and cannot be restored.
+ * @pathExample /fishery/d0145931-58d3-4561-bf64-363b61df016b?purge=true
*/
@DELETE
@Path("/{" + GRSF_RECORD_UUID_PARAMETER + "}")
@@ -256,7 +275,9 @@ public class FisheryRESTAPIs extends BaseRESTAPIs {
}
/**
- * @pathExample /fishery/bc26e8d0-6ab3-4547-9922-d40407fc5dbd
+ * This API allows to purge a fishery record.
+ * The record cannot be restored.
+ * @pathExample /fishery/d0145931-58d3-4561-bf64-363b61df016b
*/
@PURGE
@Path("/{" + GRSF_RECORD_UUID_PARAMETER + "}")
diff --git a/src/main/java/org/gcube/grsf/publisher/rest/StockRESTAPIs.java b/src/main/java/org/gcube/grsf/publisher/rest/StockRESTAPIs.java
index fc129ca..40e4d07 100644
--- a/src/main/java/org/gcube/grsf/publisher/rest/StockRESTAPIs.java
+++ b/src/main/java/org/gcube/grsf/publisher/rest/StockRESTAPIs.java
@@ -17,7 +17,6 @@ import org.gcube.grsf.publisher.annotation.PATCH;
import org.gcube.grsf.publisher.annotation.PURGE;
import org.gcube.grsf.publisher.ckan.record.StockRecord;
-import com.webcohesion.enunciate.metadata.Label;
import com.webcohesion.enunciate.metadata.rs.ResourceGroup;
import com.webcohesion.enunciate.metadata.rs.ResourceLabel;
import com.webcohesion.enunciate.metadata.rs.ResponseCode;
@@ -41,7 +40,7 @@ public class StockRESTAPIs extends BaseRESTAPIs {
/**
*
* The listing API provides paginated results by using the query parameters limit and offset.
- * It returns an array list of string containing the GRSF UUIDs of the records.
+ * It returns an array list of string containing the GRSF UUIDs of the stock records.
* Each name can be used as {stock_record_id}
path parameter to manage such a record.
*
*
@@ -184,7 +183,11 @@ public class StockRESTAPIs extends BaseRESTAPIs {
}
/**
+ * This API allows to create a stock record
* @pathExample /stock
+ *
+ * @requestExample application/json;charset=UTF-8 classpath:/api-docs-examples/stock/create-stock-request.json
+ * @responseExample application/json;charset=UTF-8 classpath:/api-docs-examples/stock/create-stock-response.json
*/
@POST
@Consumes(GCatConstants.APPLICATION_JSON_CHARSET_UTF_8)
@@ -197,7 +200,9 @@ public class StockRESTAPIs extends BaseRESTAPIs {
}
/**
- * @pathExample /stock/866a479a-643a-4c21-bbcd-a3a73f28ea50
+ * This API allows to read a stock record
+ * @pathExample /stock/23fd6734-b7cd-37eb-8b43-03b1495dd7af
+ * @responseExample application/json;charset=UTF-8 classpath:/api-docs-examples/stock/read-stock-response.json
*/
@GET
@Path("/{" + RECORD_ID_PARAMETER + "}")
@@ -211,7 +216,10 @@ public class StockRESTAPIs extends BaseRESTAPIs {
}
/**
- * @pathExample /stock/866a479a-643a-4c21-bbcd-a3a73f28ea50
+ * This API allows to update a stock record
+ * @pathExample /stock/23fd6734-b7cd-37eb-8b43-03b1495dd7af
+ * @requestExample application/json;charset=UTF-8 classpath:/api-docs-examples/fishery/create-fishery-request.json
+ * @responseExample application/json;charset=UTF-8 classpath:/api-docs-examples/fishery/create-fishery-response.json
*/
@PUT
@Path("/{" + RECORD_ID_PARAMETER + "}")
@@ -226,7 +234,13 @@ public class StockRESTAPIs extends BaseRESTAPIs {
}
/**
- * @pathExample /stock/866a479a-643a-4c21-bbcd-a3a73f28ea50
+ * This API allows to patch a stock record.
+ * The service only updates the provided properties and,
+ * eventually, creates resources (e.g., time series) and
+ * adds tags or groups to the records.
+ * The API does not guarantee that the record is removed from an
+ * old group/tag associated due to the old property value.
+ * @pathExample /stock/23fd6734-b7cd-37eb-8b43-03b1495dd7af
*/
@PATCH
@Path("/{" + RECORD_ID_PARAMETER + "}")
@@ -241,7 +255,12 @@ public class StockRESTAPIs extends BaseRESTAPIs {
}
/**
- * @pathExample /stock/866a479a-643a-4c21-bbcd-a3a73f28ea50
+ * This API allows to delete/purge (when the purge query parameter is true)
+ * a stock record.
+ * In case of delete, the stock record is no longer visible,
+ * but it still exists and can be restored.
+ * In case of purge, the record is completely deleted and cannot be restored.
+ * @pathExample /stock/23fd6734-b7cd-37eb-8b43-03b1495dd7af
*/
@DELETE
@Path("/{" + RECORD_ID_PARAMETER + "}")
@@ -256,7 +275,9 @@ public class StockRESTAPIs extends BaseRESTAPIs {
}
/**
- * @pathExample /stock/866a479a-643a-4c21-bbcd-a3a73f28ea50
+ * This API allows to purge a stock record.
+ * The record cannot be restored.
+ * @pathExample /stock/23fd6734-b7cd-37eb-8b43-03b1495dd7af
*/
@PURGE
@Path("/{" + RECORD_ID_PARAMETER + "}")
diff --git a/src/main/java/org/gcube/grsf/publisher/rest/TraceabilityUnitRESTAPIs.java b/src/main/java/org/gcube/grsf/publisher/rest/TraceabilityUnitRESTAPIs.java
index 442238d..fcdc849 100644
--- a/src/main/java/org/gcube/grsf/publisher/rest/TraceabilityUnitRESTAPIs.java
+++ b/src/main/java/org/gcube/grsf/publisher/rest/TraceabilityUnitRESTAPIs.java
@@ -17,7 +17,6 @@ import org.gcube.grsf.publisher.annotation.PATCH;
import org.gcube.grsf.publisher.annotation.PURGE;
import org.gcube.grsf.publisher.ckan.record.TraceabilityUnitRecord;
-import com.webcohesion.enunciate.metadata.Label;
import com.webcohesion.enunciate.metadata.rs.ResourceGroup;
import com.webcohesion.enunciate.metadata.rs.ResourceLabel;
import com.webcohesion.enunciate.metadata.rs.ResponseCode;
@@ -41,7 +40,7 @@ public class TraceabilityUnitRESTAPIs extends BaseRESTAPIs
* The listing API provides paginated results by using the query parameters limit and offset.
- * It returns an array list of string containing the GRSF UUIDs of the records.
+ * It returns an array list of string containing the GRSF UUIDs of the traceability unit records.
* Each name can be used as {traceability_unit_record_id}
path parameter to manage such a record.
*
*
@@ -184,7 +183,11 @@ public class TraceabilityUnitRESTAPIs extends BaseRESTAPIs