Improve Dataverse REST OpenAPI source annotations

pom.xml

@@ -1128,6 +1128,7 @@
                             <operationIdStrategy>CLASS_METHOD</operationIdStrategy>
                             <scanPackages>edu.harvard.iq.dataverse</scanPackages>
                             <scanDependenciesDisable>true</scanDependenciesDisable>
+                            <filter>edu.harvard.iq.dataverse.openapi.DataverseOpenApiFilter</filter>
                         </configuration>
                     </execution>
                 </executions>

scripts/openapi/README.md

@@ -0,0 +1,71 @@
+# OpenAPI Quality Checks
+
+This directory contains the Dataverse vacuum ruleset used to check the generated
+OpenAPI document while preserving known legacy API shapes.
+
+## vacuum
+
+vacuum is a command-line linter and quality checker for OpenAPI, AsyncAPI, and
+JSON Schema documents. It is compatible with Spectral rulesets, so the Dataverse
+ruleset can extend the built-in `vacuum:oas` recommended profile and disable
+rules that are noisy for the current API surface.
+
+Project and documentation:
+
+- GitHub: https://github.com/daveshanley/vacuum
+- Docs: https://quobix.com/vacuum
+
+Install with Homebrew:
+
+```bash
+brew install --cask daveshanley/vacuum/vacuum
+```
+
+Install with npm:
+
+```bash
+npm i -g @quobix/vacuum
+```
+
+Install with curl:
+
+```bash
+curl -fsSL https://quobix.com/scripts/install_vacuum.sh | sh
+```
+
+## Checking Dataverse OpenAPI
+
+Generate the OpenAPI document from the repository root:
+
+```bash
+mvn -q -DskipTests process-classes
+```
+
+The generated JSON is written to:
+
+```text
+target/classes/META-INF/openapi.json
+```
+
+Run the vacuum checks from the repository root:
+
+```bash
+vacuum lint -r scripts/openapi/vacuum-recommended.yaml target/classes/META-INF/openapi.json
+```
+
+For a fuller report:
+
+```bash
+vacuum report -r scripts/openapi/vacuum-recommended.yaml target/classes/META-INF/openapi.json
+```
+
+For the interactive dashboard:
+
+```bash
+vacuum dashboard -r scripts/openapi/vacuum-recommended.yaml target/classes/META-INF/openapi.json
+```
+
+The ruleset extends `vacuum:oas` recommended rules, with legacy/noisy checks
+disabled where Dataverse intentionally keeps historical endpoint names or lacks
+examples. Request-body findings remain enabled so unused body parameters on GET
+endpoints are reported and can be removed from source.

scripts/openapi/vacuum-recommended.yaml

@@ -0,0 +1,19 @@
+description: Dataverse OpenAPI recommended rules with legacy/noisy rules disabled.
+extends: [[vacuum:oas, recommended]]
+rules:
+  # Endpoint paths are historically camel case, and we won't change those for OpenAPI conformance
+  paths-kebab-case: false
+  # We do have duplications, because the same parameters as `id` will be used in multiple endpoints
+  description-duplication: false
+  # We don't have examples
+  oas3-missing-example: false
+  # We have /pids/{id}/delete --> see edu.harvard.iq.dataverse.api.Pids#deletePid
+  # The HTTP verb there is DELETE so actually we don't need to have the verb in the path,
+  #  could be fixed
+  no-http-verbs-in-path: false
+  # These endpoints have an unused `body` parameter, probably because of copy-paste.
+  # no-request-body: false would not report them, but rather we should fix them to remove `body`
+  # GET /files/{id}/prov-freeform
+  # GET /files/{id}/prov-json
+  # GET /files/{id}/prov-json
+  #no-request-body: false

src/main/java/edu/harvard/iq/dataverse/AlternativePersistentIdentifier.java

@@ -5,6 +5,7 @@
 import java.util.Date;
 
 import jakarta.persistence.*;
+import org.eclipse.microprofile.openapi.annotations.media.Schema;
 
 /**
  *
@@ -16,6 +17,7 @@
 }
 )
 @Entity
+@Schema(description = "Alternate persistent identifier assigned to a Dataverse object, including protocol, authority, identifier, and registration state.")
 public class AlternativePersistentIdentifier implements Serializable {
 
     @Id

src/main/java/edu/harvard/iq/dataverse/AuxiliaryFile.java

@@ -14,6 +14,7 @@
 import jakarta.persistence.NamedNativeQuery;
 import jakarta.persistence.NamedQueries;
 import jakarta.persistence.NamedQuery;
+import org.eclipse.microprofile.openapi.annotations.media.Schema;
 
 /**
  *
@@ -38,6 +39,7 @@
             query = "select distinct type from auxiliaryfile where datafile_id = ?1")
 })
 @Entity
+@Schema(description = "Metadata for an auxiliary file associated with a data file, including format, origin, visibility, size, checksum, and type.")
 public class AuxiliaryFile implements Serializable {
 
     @Id

src/main/java/edu/harvard/iq/dataverse/BannerMessage.java

@@ -11,13 +11,15 @@
 import jakarta.persistence.GenerationType;
 import jakarta.persistence.Id;
 import jakarta.persistence.OneToMany;
+import org.eclipse.microprofile.openapi.annotations.media.Schema;
 
 
 /**
  *
  * @author skraffmi
  */
 @Entity
+@Schema(description = "Site banner message configuration, including active state, dismissibility, and localized message text.")
 public class BannerMessage implements Serializable {
 
     @Id

src/main/java/edu/harvard/iq/dataverse/BannerMessageText.java

@@ -13,12 +13,14 @@
 import jakarta.persistence.Id;
 import jakarta.persistence.JoinColumn;
 import jakarta.persistence.ManyToOne;
+import org.eclipse.microprofile.openapi.annotations.media.Schema;
 
 /**
  *
  * @author skraffmi
  */
 @Entity
+@Schema(description = "Localized banner message text, including the language code and message content.")
 public class BannerMessageText implements Serializable {
 
     @Id

src/main/java/edu/harvard/iq/dataverse/DatasetLock.java

@@ -38,6 +38,7 @@
 import jakarta.persistence.TemporalType;
 import jakarta.persistence.NamedQueries;
 import jakarta.persistence.NamedQuery;
+import org.eclipse.microprofile.openapi.annotations.media.Schema;
 
 /**
  *
@@ -64,6 +65,7 @@
 )
 public class DatasetLock implements Serializable {
 
+    @Schema(description = "Dataset lock reason indicating why dataset editing or publication is blocked.")
     public enum Reason {
         /** Data being ingested *//** Data being ingested */
         Ingest,

src/main/java/edu/harvard/iq/dataverse/DvObject.java

@@ -11,6 +11,7 @@
 import java.util.logging.Logger;
 
 import jakarta.persistence.*;
+import org.eclipse.microprofile.openapi.annotations.media.Schema;
 
 /**
  * Base of the object hierarchy for "anything that can be inside a dataverse".
@@ -58,6 +59,7 @@ public abstract class DvObject extends DataverseEntity implements java.io.Serial
 
     private static final Logger logger = Logger.getLogger(DvObject.class.getCanonicalName());
 
+    @Schema(description = "Dataverse object type discriminator for dataverses, datasets, and data files.")
     public enum DType {
         Dataverse("Dataverse"), Dataset("Dataset"),DataFile("DataFile");