From 91c038b52d8d3c11d9796e2017772b0a7a11c9ad Mon Sep 17 00:00:00 2001 From: Matthew Blissett Date: Fri, 17 Mar 2023 14:07:07 +0100 Subject: [PATCH] Finish derived dataset. --- .../ws/DerivedDatasetCreationRequest.java | 3 +- .../ws/resources/DatasetResource.java | 9 ++-- .../ws/resources/DerivedDatasetResource.java | 47 ++++++++++--------- .../registry/ws/resources/NodeResource.java | 4 +- 4 files changed, 32 insertions(+), 31 deletions(-) diff --git a/registry-domain/src/main/java/org/gbif/registry/domain/ws/DerivedDatasetCreationRequest.java b/registry-domain/src/main/java/org/gbif/registry/domain/ws/DerivedDatasetCreationRequest.java index b6008afea..332f1dcfd 100644 --- a/registry-domain/src/main/java/org/gbif/registry/domain/ws/DerivedDatasetCreationRequest.java +++ b/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; diff --git a/registry-ws/src/main/java/org/gbif/registry/ws/resources/DatasetResource.java b/registry-ws/src/main/java/org/gbif/registry/ws/resources/DatasetResource.java index 29f87aaa8..707317e9f 100644 --- a/registry-ws/src/main/java/org/gbif/registry/ws/resources/DatasetResource.java +++ b/registry-ws/src/main/java/org/gbif/registry/ws/resources/DatasetResource.java @@ -1108,15 +1108,15 @@ public List 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 diff --git a/registry-ws/src/main/java/org/gbif/registry/ws/resources/DerivedDatasetResource.java b/registry-ws/src/main/java/org/gbif/registry/ws/resources/DerivedDatasetResource.java index 286c52699..1e60cb001 100644 --- a/registry-ws/src/main/java/org/gbif/registry/ws/resources/DerivedDatasetResource.java +++ b/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 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 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 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 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", diff --git a/registry-ws/src/main/java/org/gbif/registry/ws/resources/NodeResource.java b/registry-ws/src/main/java/org/gbif/registry/ws/resources/NodeResource.java index b4c60064d..37ce50803 100644 --- a/registry-ws/src/main/java/org/gbif/registry/ws/resources/NodeResource.java +++ b/registry-ws/src/main/java/org/gbif/registry/ws/resources/NodeResource.java @@ -379,9 +379,9 @@ public PagingResponse 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)); }