Improve Dataverse REST OpenAPI source annotations#12439
Open
beepsoft wants to merge 4 commits into
Open
Conversation
Add source-level OpenAPI annotations across Dataverse REST resources, including class tags, operation summaries/descriptions, parameter and request-body docs, API key security metadata, and response schema fixes for generated OpenAPI/MCP tooling. IQSS#12437 describes this effort in more details
![github-advanced-security[bot]](https://avatars.githubusercontent.com/in/57789?s=60&v=4){kind=small}
| description = "Updates or creates a draft dataset version from JSON-LD metadata.") | ||
| @SecurityRequirement(name = "DataverseApiKey") | ||
| public Response updateVersionMetadata(@Context ContainerRequestContext crc, | ||
| @RequestBody(description = "JSON-LD metadata to apply to the dataset draft.") |
| @AuthRequired | ||
| @Path("datasetTypes/{id}") | ||
| public Response deleteDatasetType(@Context ContainerRequestContext crc, @PathParam("id") String doomed) { | ||
| @Operation(summary = "Remove a dataset type", |
| @PUT | ||
| @Path("datasetTypes/{idOrName}") | ||
| public Response updateDatasetTypeLinksWithMetadataBlocks(@Context ContainerRequestContext crc, @PathParam("idOrName") String idOrName, String jsonBody) { | ||
| @Operation(summary = "Link metadata blocks to a dataset type", |
Contributor
|
Please assign me as a reviewer :) |
Contributor
Author
|
@srmanda-cs I don't think I have permissions to do it here. @pdurbin can you maybe help, please? |
Member
|
@srmanda-cs I just sent an invite. Please accept it at https://github.com/IQSS Afterwards, you'll be part of https://github.com/orgs/IQSS/teams/dataverse-readonly which means I'll be able to assign issues and PRs to you (so look out! 😜 ). |
Contributor
Thank you so much! |
pdurbin
moved this from Ready for Triage
to Ready for Review ⏩
in IQSS Dataverse Project
Member
Enable DataverseOpenApiFilter in the SmallRye OpenAPI Maven generation and add the filter implementation to normalize generated API docs after annotation scanning. The filter adds the Dataverse API key security scheme, rewrites selected Access download responses as binary wire payloads instead of internal writer helper schemas, removes a known circular schema back-reference, and prunes component schemas no longer reachable from public operations.
Update Dataverse REST API source annotations to make the generated OpenAPI document more complete and better aligned with the vacuum linter ruleset. See scripts/openapi/README.md for running vacuum. Add missing operation summaries, parameter descriptions, request body descriptions, security requirements, response metadata, and schema descriptions across API resources and exposed DTO/model classes. Refine binary response schemas and remove duplicate API key security scheme metadata.
# Conflicts: # src/main/java/edu/harvard/iq/dataverse/api/Access.java # src/main/java/edu/harvard/iq/dataverse/api/Datasets.java # src/main/java/edu/harvard/iq/dataverse/api/Dataverses.java # src/main/java/edu/harvard/iq/dataverse/api/Guestbooks.java
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
4 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Add source-level OpenAPI annotations across Dataverse REST resources, including class tags, operation summaries/descriptions, parameter and request-body docs, API key security metadata, and response schema fixes for generated OpenAPI/MCP tooling.
What this PR does / why we need it:
Ongoing discussions in #12437.
Special notes for your reviewer:
This PR affects 580 endpoints (Java methods), which means we updated 45 Java files for this, which all need to be reviewed.
Suggestions on how to test this:
See what is returned by the
/openapior/openapi?format=jsonendpoint.Does this PR introduce a user interface change? If mockups are available, please link/include them here:
No.