Finish derived dataset.

registry-domain/src/main/java/org/gbif/registry/domain/ws/DerivedDatasetCreationRequest.java

@@ -62,7 +62,8 @@ public class DerivedDatasetCreationRequest implements Serializable {
   private URI sourceUrl;
 
   @Schema(
-    description = "" // TODO
+    description = "A future date should you wish to delay the registration of the DOI, " +
+      "for example for embargoed materials."
   )
   private Date registrationDate;
 

registry-ws/src/main/java/org/gbif/registry/ws/resources/DatasetResource.java

@@ -1108,15 +1108,15 @@ public List<Network> listNetworks(@PathVariable("key") UUID datasetKey) {
     return networkMapper.list(NetworkListParams.builder().datasetKey(datasetKey).build());
   }
 
-  // TODO: What for?
+  @Hidden
   @Operation(
       operationId = "getAllConstituents",
-      summary = "Retrieve all constituent datasets",
+      summary = "List all constituent datasets",
       description = "Lists datasets that are a constituent of any dataset.",
       extensions =
           @Extension(
               name = "Order",
-              properties = @ExtensionProperty(name = "Order", value = "0230")))
+              properties = @ExtensionProperty(name = "Order", value = "0500")))
   @Pageable.OffsetLimitParameters
   @ApiResponse(responseCode = "200", description = "List of datasets")
   @Docs.DefaultUnsuccessfulReadResponses
@@ -1220,7 +1220,7 @@ public void deleteMetadata(@PathVariable("metadataKey") int metadataKey) {
       extensions =
           @Extension(
               name = "Order",
-              properties = @ExtensionProperty(name = "Order", value = "0500")))
+              properties = @ExtensionProperty(name = "Order", value = "0505")))
   @Parameters(
       value = {
         @Parameter(
@@ -1238,7 +1238,6 @@ public void deleteMetadata(@PathVariable("metadataKey") int metadataKey) {
             explode = Explode.TRUE)
       })
   @SimpleSearchParameters
-  @CommonParameters.QParameter
   @Pageable.OffsetLimitParameters
   @ApiResponse(responseCode = "200", description = "List of deleted datasets")
   @Docs.DefaultUnsuccessfulReadResponses

registry-ws/src/main/java/org/gbif/registry/ws/resources/DerivedDatasetResource.java

@@ -62,6 +62,8 @@
 import org.springframework.web.multipart.MultipartFile;
 import org.springframework.web.server.ResponseStatusException;
 
+import io.swagger.v3.oas.annotations.ExternalDocumentation;
+import io.swagger.v3.oas.annotations.Hidden;
 import io.swagger.v3.oas.annotations.Operation;
 import io.swagger.v3.oas.annotations.Parameter;
 import io.swagger.v3.oas.annotations.extensions.Extension;
@@ -74,9 +76,11 @@
 import static org.gbif.registry.security.UserRoles.ADMIN_ROLE;
 import static org.gbif.registry.security.UserRoles.USER_ROLE;
 
-@Tag(name = "Derived datasets", description = "Derived datasets are metadata records allowing the citation of a " +
+@Tag(name = "Derived datasets",
+  description = "Derived datasets are metadata records allowing the citation of a " +
   "subset of a larger dataset.  Typically the large dataset is a monthly download containing all GBIF occurrences " +
-  "and made available on a public cloud service.")
+  "and made available on a public cloud service.",
+  externalDocs = @ExternalDocumentation(description = "GBIF data blog article", url = "https://data-blog.gbif.org/post/derived-datasets/"))
 @RestController
 @RequestMapping(path = "derivedDataset", produces = MediaType.APPLICATION_JSON_VALUE)
 @Validated
@@ -105,29 +109,26 @@ public DerivedDatasetResource(
     summary = "Create a new derived dataset",
     description = "Creates a new derived dataset with the specified source dataset and records of what subset " +
       "should be cited.",
-    extensions = @Extension(name = "Order", properties = @ExtensionProperty(name = "Order", value = "0201.1")))
+    extensions = @Extension(name = "Order", properties = @ExtensionProperty(name = "Order", value = "0100")))
   @ApiResponse(
     responseCode = "201",
     description = "Derived dataset information.")
   @Secured({ADMIN_ROLE, USER_ROLE})
   @Validated({PrePersist.class, Default.class})
   @PostMapping(consumes = MediaType.APPLICATION_JSON_VALUE)
-  public DerivedDataset create(@RequestBody @Valid DerivedDatasetCreationRequest request) {
+  public DerivedDataset create(
+    @io.swagger.v3.oas.annotations.parameters.RequestBody(
+      description = "The request body should contain the parameters below.  Note the `relatedDatasets` map " +
+        "may use GBIF Dataset DOIs or UUIDs as keys, with the values being the number of records to cite " +
+        "from each dataset."
+    )
+    @RequestBody @Valid DerivedDatasetCreationRequest request) {
     return createDerivedDataset(request, request.getRelatedDatasets());
   }
 
-  @Operation(
-    operationId = "createDerivedDatasetFromFile",
-    summary = "Create a new derived dataset from a file",
-    description = "Creates a new derived dataset with the specified source dataset and records of what subset " +
-      "should be cited.",
-    extensions = @Extension(name = "Order", properties = @ExtensionProperty(name = "Order", value = "0201.2")))
-  @io.swagger.v3.oas.annotations.parameters.RequestBody(
-    description = "File body TODO" // TODO
-  )
-  @ApiResponse(
-    responseCode = "201",
-    description = "Derived dataset information.")
+  // It seems complicated to document the multipart form upload, and it's probably
+  // only intended for use on the website anyway.
+  @Hidden
   @Secured({ADMIN_ROLE, USER_ROLE})
   @Validated({PrePersist.class, Default.class})
   @PostMapping(consumes = MediaType.MULTIPART_FORM_DATA_VALUE)
@@ -198,7 +199,7 @@ public DerivedDataset getDerivedDataset(DOI doi) {
     description = "Updates the values of a derived dataset.\n\n" +
       "This is restricted to administrators, contact the [helpdesk](https://www.gbif.org/contact-us) " +
       "for assistance.",
-    extensions = @Extension(name = "Order", properties = @ExtensionProperty(name = "Order", value = "0202")))
+    extensions = @Extension(name = "Order", properties = @ExtensionProperty(name = "Order", value = "0105")))
   @ApiResponse(
     responseCode = "201",
     description = "Derived dataset updated.")
@@ -250,7 +251,7 @@ && checkIsNotAdmin(authentication)) {
   @Operation(
     operationId = "getDerivedDatasetByDoi",
     summary = "Retrieve a derived dataset record",
-    extensions = @Extension(name = "Order", properties = @ExtensionProperty(name = "Order", value = "0200.1")))
+    extensions = @Extension(name = "Order", properties = @ExtensionProperty(name = "Order", value = "0105")))
   @ApiResponse(
     responseCode = "200",
     description = "Derived dataset information.")
@@ -265,7 +266,7 @@ public ResponseEntity<DerivedDataset> getDerivedDataset(
   @Operation(
     operationId = "getDerivedDatasetByDatasetKey",
     summary = "Retrieve derived datasets of a dataset by key",
-    extensions = @Extension(name = "Order", properties = @ExtensionProperty(name = "Order", value = "0200.2")))
+    extensions = @Extension(name = "Order", properties = @ExtensionProperty(name = "Order", value = "0110")))
   @Parameter(
     name = "key",
     description = "Dataset key",
@@ -285,7 +286,7 @@ public PagingResponse<DerivedDataset> getDerivedDatasets(
   @Operation(
     operationId = "getDerivedDatasetByDatasetDoi",
     summary = "Retrieve derived datasets of a dataset by DOI",
-    extensions = @Extension(name = "Order", properties = @ExtensionProperty(name = "Order", value = "0200.3")))
+    extensions = @Extension(name = "Order", properties = @ExtensionProperty(name = "Order", value = "0120")))
   @Pageable.OffsetLimitParameters
   @ApiResponse(
     responseCode = "200",
@@ -302,7 +303,7 @@ public PagingResponse<DerivedDataset> getDerivedDatasets(
   @Operation(
     operationId = "getDerivedDatasetByUser",
     summary = "Retrieve derived datasets of a dataset by User",
-    extensions = @Extension(name = "Order", properties = @ExtensionProperty(name = "Order", value = "0200.4")))
+    extensions = @Extension(name = "Order", properties = @ExtensionProperty(name = "Order", value = "0130")))
   @Pageable.OffsetLimitParameters
   @ApiResponse(
     responseCode = "200",
@@ -331,7 +332,7 @@ public String getCitationText(DOI doi) {
   @Operation(
     operationId = "getDerivedDatasetCitation",
     summary = "Retrieve derived dataset citation",
-    extensions = @Extension(name = "Order", properties = @ExtensionProperty(name = "Order", value = "0210")))
+    extensions = @Extension(name = "Order", properties = @ExtensionProperty(name = "Order", value = "0200")))
   @Pageable.OffsetLimitParameters
   @ApiResponse(
     responseCode = "200",
@@ -352,7 +353,7 @@ public PagingResponse<DerivedDatasetUsage> getRelatedDatasets(
   @Operation(
     operationId = "getDerivedDatasetRelatedDatasets",
     summary = "Retrieve derived dataset related datasets",
-    extensions = @Extension(name = "Order", properties = @ExtensionProperty(name = "Order", value = "0220")))
+    extensions = @Extension(name = "Order", properties = @ExtensionProperty(name = "Order", value = "0210")))
   @Pageable.OffsetLimitParameters
   @ApiResponse(
     responseCode = "200",

registry-ws/src/main/java/org/gbif/registry/ws/resources/NodeResource.java

@@ -379,9 +379,9 @@ public PagingResponse<Organization> pendingEndorsements(
               properties = @ExtensionProperty(name = "Order", value = "0250")))
   @ApiResponse(responseCode = "200", description = "Country node")
   @Docs.DefaultUnsuccessfulReadResponses
-  @GetMapping("country/{key}")
+  @GetMapping("country/{countryCode}")
   @Nullable
-  public Node getByCountry(@PathVariable("key") String isoCode) {
+  public Node getByCountry(@PathVariable("countryCode") String isoCode) {
     return getByCountry(Country.fromIsoCode(isoCode));
   }