From 985b3494cf554861ba48ae88406a8fae647fbb04 Mon Sep 17 00:00:00 2001
From: "Balazs E. Pataki" <pataki@gmail.com>
Date: Tue, 2 Jun 2026 22:35:52 +0200
Subject: [PATCH] Improve Dataverse REST OpenAPI source annotations

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.

#12437 describes this effort in more details
---
 .../edu/harvard/iq/dataverse/api/Access.java  | 103 +++-
 .../edu/harvard/iq/dataverse/api/Admin.java   | 444 ++++++++++++--
 .../iq/dataverse/api/ApiConfiguration.java    |  10 +
 .../harvard/iq/dataverse/api/BatchImport.java |  41 +-
 .../iq/dataverse/api/BuiltinUsers.java        |  47 +-
 .../harvard/iq/dataverse/api/DataTagsAPI.java |  15 +-
 .../dataverse/api/DatasetFieldServiceApi.java |  37 +-
 .../iq/dataverse/api/DatasetFields.java       |   5 +
 .../harvard/iq/dataverse/api/Datasets.java    | 289 ++++++++-
 .../dataverse/api/DataverseFeaturedItems.java |  22 +-
 .../harvard/iq/dataverse/api/Dataverses.java  | 563 ++++++++++++++++--
 .../edu/harvard/iq/dataverse/api/EditDDI.java |  15 +-
 .../iq/dataverse/api/ExternalTools.java       |  25 +-
 .../iq/dataverse/api/ExternalToolsApi.java    |  28 +-
 .../harvard/iq/dataverse/api/FeedbackApi.java |  12 +-
 .../edu/harvard/iq/dataverse/api/Files.java   | 122 +++-
 .../edu/harvard/iq/dataverse/api/Groups.java  |  75 ++-
 .../harvard/iq/dataverse/api/Guestbooks.java  |  41 +-
 .../iq/dataverse/api/HarvestingClients.java   |  55 +-
 .../iq/dataverse/api/HarvestingServer.java    |  57 +-
 .../edu/harvard/iq/dataverse/api/Index.java   |  46 +-
 .../edu/harvard/iq/dataverse/api/Info.java    |  33 +-
 .../harvard/iq/dataverse/api/Licenses.java    |  55 +-
 .../iq/dataverse/api/LocalContexts.java       |  22 +-
 .../edu/harvard/iq/dataverse/api/Logout.java  |   5 +
 .../edu/harvard/iq/dataverse/api/Mail.java    |   5 +
 .../iq/dataverse/api/MakeDataCountApi.java    |  48 +-
 .../harvard/iq/dataverse/api/Metadata.java    |  26 +-
 .../iq/dataverse/api/MetadataBlocks.java      |  19 +-
 .../edu/harvard/iq/dataverse/api/Metrics.java | 288 +++++++--
 .../iq/dataverse/api/Notifications.java       |  54 +-
 .../edu/harvard/iq/dataverse/api/Pids.java    |  38 +-
 .../edu/harvard/iq/dataverse/api/Prov.java    |  49 +-
 .../edu/harvard/iq/dataverse/api/Roles.java   |  28 +-
 .../iq/dataverse/api/SavedSearches.java       |  43 +-
 .../edu/harvard/iq/dataverse/api/Search.java  |   5 +
 .../iq/dataverse/api/SendFeedbackAPI.java     |  14 +-
 .../edu/harvard/iq/dataverse/api/SiteMap.java |   5 +
 .../iq/dataverse/api/StorageSites.java        |  33 +-
 .../edu/harvard/iq/dataverse/api/Users.java   |  78 ++-
 .../harvard/iq/dataverse/api/Workflows.java   |  13 +-
 .../iq/dataverse/api/WorkflowsAdmin.java      |  57 +-
 .../api/batchjob/BatchJobResource.java        |  20 +-
 .../api/batchjob/FileRecordJobResource.java   |  12 +
 44 files changed, 2655 insertions(+), 347 deletions(-)

diff --git a/src/main/java/edu/harvard/iq/dataverse/api/Access.java b/src/main/java/edu/harvard/iq/dataverse/api/Access.java
index c3c74f49019..dc8eb4eb57c 100644
--- a/src/main/java/edu/harvard/iq/dataverse/api/Access.java
+++ b/src/main/java/edu/harvard/iq/dataverse/api/Access.java
@@ -45,9 +45,11 @@
 import jakarta.ws.rs.core.*;
 import org.eclipse.microprofile.openapi.annotations.Operation;
 import org.eclipse.microprofile.openapi.annotations.media.Content;
+import org.eclipse.microprofile.openapi.annotations.parameters.Parameter;
 import org.eclipse.microprofile.openapi.annotations.parameters.RequestBody;
 import org.eclipse.microprofile.openapi.annotations.responses.APIResponse;
 import org.eclipse.microprofile.openapi.annotations.responses.APIResponses;
+import org.eclipse.microprofile.openapi.annotations.security.SecurityRequirement;
 import org.eclipse.microprofile.openapi.annotations.tags.Tag;
 import org.glassfish.jersey.media.multipart.FormDataBodyPart;
 import org.glassfish.jersey.media.multipart.FormDataParam;
@@ -88,6 +90,7 @@
  */
 
 @Path("access")
+@Tag(name = "Access", description = "Download files, bundles, citations, metadata, and access-related file assets.")
 public class Access extends AbstractApiBean {
     private static final Logger logger = Logger.getLogger(Access.class.getCanonicalName());
         
@@ -162,8 +165,18 @@ public Response datafileCitation(@Context ContainerRequestContext crc,
     @AuthRequired
     @Path("datafile/bundle/{fileId}")
     @Produces({"application/zip"})
-    public BundleDownloadInstance datafileBundle(@Context ContainerRequestContext crc, @PathParam("fileId") String fileId, @QueryParam("fileMetadataId") Long fileMetadataId,
-                                                 @QueryParam("gbrecs") boolean gbrecs, @QueryParam("gbrids") String gbrids,
+    @Operation(summary = "Build a file bundle",
+            description = "Streams a ZIP bundle for a data file, including citation exports and optional tabular metadata when available.")
+    @SecurityRequirement(name = "DataverseApiKey")
+    public BundleDownloadInstance datafileBundle(@Context ContainerRequestContext crc,
+                                                 @Parameter(description = "Data file id or persistent identifier for the bundle.", required = true)
+                                                 @PathParam("fileId") String fileId,
+                                                 @Parameter(description = "File metadata id used to select a specific file metadata record.")
+                                                 @QueryParam("fileMetadataId") Long fileMetadataId,
+                                                 @Parameter(description = "Whether guestbook records have already been written for this download.")
+                                                 @QueryParam("gbrecs") boolean gbrecs,
+                                                 @Parameter(description = "Guestbook response id list supplied by the user interface.")
+                                                 @QueryParam("gbrids") String gbrids,
                                                  @Context UriInfo uriInfo, @Context HttpHeaders headers, @Context HttpServletResponse response) /*throws NotFoundException, ServiceUnavailableException, PermissionDeniedException, AuthorizationRequiredException*/ {
 
         DataFile df = findDataFileOrDieWrapper(fileId);
@@ -224,8 +237,21 @@ public BundleDownloadInstance datafileBundle(@Context ContainerRequestContext cr
     @AuthRequired
     @Path("datafile/bundle/{fileId}")
     @Produces({"application/zip"})
-    public BundleDownloadInstance datafileBundleWithGuestbookResponse(@Context ContainerRequestContext crc, @PathParam("fileId") String fileId, @QueryParam("fileMetadataId") Long fileMetadataId, @QueryParam("gbrecs") boolean gbrecs, @QueryParam("gbrids") String gbrids,
-                                                                      @Context UriInfo uriInfo, @Context HttpHeaders headers, @Context HttpServletResponse response, String jsonBody) /*throws NotFoundException, ServiceUnavailableException, PermissionDeniedException, AuthorizationRequiredException*/ {
+    @Operation(summary = "Submit guestbook response for a file bundle",
+            description = "Records the supplied guestbook response and then streams the ZIP bundle for a data file.")
+    @SecurityRequirement(name = "DataverseApiKey")
+    public BundleDownloadInstance datafileBundleWithGuestbookResponse(@Context ContainerRequestContext crc,
+                                                                      @Parameter(description = "Data file id or persistent identifier for the bundle.", required = true)
+                                                                      @PathParam("fileId") String fileId,
+                                                                      @Parameter(description = "File metadata id used to select a specific file metadata record.")
+                                                                      @QueryParam("fileMetadataId") Long fileMetadataId,
+                                                                      @Parameter(description = "Whether guestbook records have already been written for this download.")
+                                                                      @QueryParam("gbrecs") boolean gbrecs,
+                                                                      @Parameter(description = "Guestbook response id list supplied by the user interface.")
+                                                                      @QueryParam("gbrids") String gbrids,
+                                                                      @Context UriInfo uriInfo, @Context HttpHeaders headers, @Context HttpServletResponse response,
+                                                                      @RequestBody(description = "Guestbook response JSON for the requested data file.")
+                                                                      String jsonBody) /*throws NotFoundException, ServiceUnavailableException, PermissionDeniedException, AuthorizationRequiredException*/ {
 
         processDatafileWithGuestbookResponse(crc, headers, fileId, uriInfo, gbrecs, jsonBody);
         // JSF UI passes the guestbook response id(s) in thus this qp can be removed when JSF is removed
@@ -406,8 +432,17 @@ public Response datafile(@Context ContainerRequestContext crc, @PathParam("fileI
     @AuthRequired
     @Path("datafile/{fileId:.+}")
     @Produces({"application/json"})
-    public Response datafileWithGuestbookResponse(@Context ContainerRequestContext crc, @PathParam("fileId") String fileId,
-                                                  @QueryParam("gbrecs") boolean gbrecs, @Context UriInfo uriInfo, @Context HttpHeaders headers, @Context HttpServletResponse response, String jsonBody) {
+    @Operation(summary = "Submit guestbook response for a data file",
+            description = "Records the supplied guestbook response and returns access details for a data file download.")
+    @SecurityRequirement(name = "DataverseApiKey")
+    public Response datafileWithGuestbookResponse(@Context ContainerRequestContext crc,
+                                                  @Parameter(description = "Data file id, persistent identifier, or path-style file reference.", required = true)
+                                                  @PathParam("fileId") String fileId,
+                                                  @Parameter(description = "Whether guestbook records have already been written for this download.")
+                                                  @QueryParam("gbrecs") boolean gbrecs,
+                                                  @Context UriInfo uriInfo, @Context HttpHeaders headers, @Context HttpServletResponse response,
+                                                  @RequestBody(description = "Guestbook response JSON for the requested data file.")
+                                                  String jsonBody) {
 
         fileId = normalizeFileId(fileId);
         return processDatafileWithGuestbookResponse(crc, headers, fileId, uriInfo, gbrecs, jsonBody);
@@ -579,7 +614,19 @@ private Response returnSignedUrl(ContainerRequestContext crc, UriInfo uriInfo, U
     @AuthRequired
     @Path("datafile/{fileId}/metadata")
     @Produces({"text/xml"})
-    public String tabularDatafileMetadata(@Context ContainerRequestContext crc, @PathParam("fileId") String fileId, @QueryParam("fileMetadataId") Long fileMetadataId, @QueryParam("exclude") String exclude, @QueryParam("include") String include, @Context HttpHeaders header, @Context HttpServletResponse response) throws NotFoundException, ServiceUnavailableException /*, PermissionDeniedException, AuthorizationRequiredException*/ {
+    @Operation(summary = "Export tabular file metadata",
+            description = "Streams tabular data file metadata in the default DDI XML format.")
+    @SecurityRequirement(name = "DataverseApiKey")
+    public String tabularDatafileMetadata(@Context ContainerRequestContext crc,
+                                          @Parameter(description = "Data file id or persistent identifier for the tabular file.", required = true)
+                                          @PathParam("fileId") String fileId,
+                                          @Parameter(description = "File metadata id used to select a specific file metadata record.")
+                                          @QueryParam("fileMetadataId") Long fileMetadataId,
+                                          @Parameter(description = "Comma-separated metadata sections to exclude from the export.")
+                                          @QueryParam("exclude") String exclude,
+                                          @Parameter(description = "Comma-separated metadata sections to include in the export.")
+                                          @QueryParam("include") String include,
+                                          @Context HttpHeaders header, @Context HttpServletResponse response) throws NotFoundException, ServiceUnavailableException /*, PermissionDeniedException, AuthorizationRequiredException*/ {
         return tabularDatafileMetadataDDI(crc, fileId, fileMetadataId, exclude, include, header, response);
     }
     
@@ -591,7 +638,19 @@ public String tabularDatafileMetadata(@Context ContainerRequestContext crc, @Pat
     @AuthRequired
     @GET
     @Produces({"text/xml"})
-    public String tabularDatafileMetadataDDI(@Context ContainerRequestContext crc, @PathParam("fileId") String fileId, @QueryParam("fileMetadataId") Long fileMetadataId, @QueryParam("exclude") String exclude, @QueryParam("include") String include, @Context HttpHeaders header, @Context HttpServletResponse response) throws NotFoundException, ServiceUnavailableException /*, PermissionDeniedException, AuthorizationRequiredException*/ {
+    @Operation(summary = "Export tabular file metadata as DDI",
+            description = "Streams DDI XML metadata for a tabular data file.")
+    @SecurityRequirement(name = "DataverseApiKey")
+    public String tabularDatafileMetadataDDI(@Context ContainerRequestContext crc,
+                                             @Parameter(description = "Data file id or persistent identifier for the tabular file.", required = true)
+                                             @PathParam("fileId") String fileId,
+                                             @Parameter(description = "File metadata id used to select a specific file metadata record.")
+                                             @QueryParam("fileMetadataId") Long fileMetadataId,
+                                             @Parameter(description = "Comma-separated metadata sections to exclude from the export.")
+                                             @QueryParam("exclude") String exclude,
+                                             @Parameter(description = "Comma-separated metadata sections to include in the export.")
+                                             @QueryParam("include") String include,
+                                             @Context HttpHeaders header, @Context HttpServletResponse response) throws NotFoundException, ServiceUnavailableException /*, PermissionDeniedException, AuthorizationRequiredException*/ {
         String retValue = "";
 
         DataFile dataFile = null; 
@@ -799,7 +858,17 @@ public DownloadInstance downloadAuxiliaryFile(@Context ContainerRequestContext c
     @Path("datafiles")
     @Consumes("text/plain")
     @Produces({ "application/zip" })
-    public Response postDownloadDatafiles(@Context ContainerRequestContext crc, String body, @QueryParam("gbrecs") boolean gbrecs, @QueryParam("gbrids") String gbrids, @Context UriInfo uriInfo, @Context HttpHeaders headers, @Context HttpServletResponse response) throws WebApplicationException {
+    @Operation(summary = "Stream a ZIP for selected files",
+            description = "Accepts a text list of data file ids and streams the selected files as a ZIP archive.")
+    @SecurityRequirement(name = "DataverseApiKey")
+    public Response postDownloadDatafiles(@Context ContainerRequestContext crc,
+                                          @RequestBody(description = "Text list of data file ids to include in the ZIP archive.")
+                                          String body,
+                                          @Parameter(description = "Whether guestbook records have already been written for this download.")
+                                          @QueryParam("gbrecs") boolean gbrecs,
+                                          @Parameter(description = "Guestbook response id list supplied by the user interface.")
+                                          @QueryParam("gbrids") String gbrids,
+                                          @Context UriInfo uriInfo, @Context HttpHeaders headers, @Context HttpServletResponse response) throws WebApplicationException {
 
         processDatafileWithGuestbookResponse(crc, headers, body, uriInfo, gbrecs, body);
         // JSF UI passes the guestbook response id(s) in thus this qp can be removed when JSF is removed
@@ -861,7 +930,17 @@ public Response downloadAllFromLatest(@Context ContainerRequestContext crc, @Pat
     @AuthRequired
     @Path("dataset/{id}")
     @Produces({"application/zip"})
-    public Response downloadAllFromLatestWithGuestbookResponse(@Context ContainerRequestContext crc, @PathParam("id") String datasetIdOrPersistentId, @QueryParam("gbrecs") boolean gbrecs, @Context UriInfo uriInfo, @Context HttpHeaders headers, @Context HttpServletResponse response, String jsonBody) throws WebApplicationException {
+    @Operation(summary = "Submit guestbook response for latest dataset files",
+            description = "Records a guestbook response and prepares a ZIP download for files in the latest accessible dataset version.")
+    @SecurityRequirement(name = "DataverseApiKey")
+    public Response downloadAllFromLatestWithGuestbookResponse(@Context ContainerRequestContext crc,
+                                                               @Parameter(description = "Dataset id or persistent identifier.", required = true)
+                                                               @PathParam("id") String datasetIdOrPersistentId,
+                                                               @Parameter(description = "Whether guestbook records have already been written for this download.")
+                                                               @QueryParam("gbrecs") boolean gbrecs,
+                                                               @Context UriInfo uriInfo, @Context HttpHeaders headers, @Context HttpServletResponse response,
+                                                               @RequestBody(description = "Guestbook response JSON for the dataset file download.")
+                                                               String jsonBody) throws WebApplicationException {
         try {
             User user = getRequestUser(crc);
             DataverseRequest req = createDataverseRequest(user);
@@ -1290,7 +1369,9 @@ public InputStream fileCardImage(@PathParam("fileId") Long fileId, @Context UriI
     @Path("dsCardImage/{versionId}")
     @GET
     @Produces({ "image/png" })
-    public InputStream dsCardImage(@PathParam("versionId") Long versionId, @Context UriInfo uriInfo, @Context HttpHeaders headers, @Context HttpServletResponse response) /*throws NotFoundException, ServiceUnavailableException, PermissionDeniedException, AuthorizationRequiredException*/ {        
+    public InputStream dsCardImage(@Parameter(description = "Dataset version id used to locate the card image.", required = true)
+                                   @PathParam("versionId") Long versionId,
+                                   @Context UriInfo uriInfo, @Context HttpHeaders headers, @Context HttpServletResponse response) /*throws NotFoundException, ServiceUnavailableException, PermissionDeniedException, AuthorizationRequiredException*/ {
         
         
         DatasetVersion datasetVersion = versionService.find(versionId);
diff --git a/src/main/java/edu/harvard/iq/dataverse/api/Admin.java b/src/main/java/edu/harvard/iq/dataverse/api/Admin.java
index 1eecdd4b171..0acfb8a80b0 100644
--- a/src/main/java/edu/harvard/iq/dataverse/api/Admin.java
+++ b/src/main/java/edu/harvard/iq/dataverse/api/Admin.java
@@ -135,10 +135,15 @@
 import jakarta.ws.rs.QueryParam;
 import jakarta.ws.rs.WebApplicationException;
 import jakarta.ws.rs.core.StreamingOutput;
+import org.eclipse.microprofile.openapi.annotations.Operation;
 import org.eclipse.microprofile.openapi.annotations.media.Content;
 import org.eclipse.microprofile.openapi.annotations.media.Schema;
+import org.eclipse.microprofile.openapi.annotations.parameters.Parameter;
+import org.eclipse.microprofile.openapi.annotations.parameters.RequestBody;
 import org.eclipse.microprofile.openapi.annotations.responses.APIResponse;
 import org.eclipse.microprofile.openapi.annotations.responses.APIResponses;
+import org.eclipse.microprofile.openapi.annotations.security.SecurityRequirement;
+import org.eclipse.microprofile.openapi.annotations.tags.Tag;
 
 import java.nio.file.Paths;
 import java.util.TreeMap;
@@ -150,6 +155,7 @@
  */
 @Stateless
 @Path("admin")
+@Tag(name = "Admin", description = "Administrative settings, users, roles, indexing, validation, and maintenance operations.")
 public class Admin extends AbstractApiBean {
 
     private static final Logger logger = Logger.getLogger(Admin.class.getName());
@@ -204,6 +210,8 @@ public class Admin extends AbstractApiBean {
     
     @Path("settings")
     @GET
+    @Operation(summary = "Enumerate database settings",
+            description = "Lists all Dataverse database settings as a JSON object.")
     @APIResponses({
         @APIResponse(responseCode = "200",
             description = "All database options successfully queried",
@@ -217,10 +225,13 @@ public Response listAllSettings() {
     @Path("settings")
     @PUT
     @Consumes(MediaType.APPLICATION_JSON)
+    @Operation(summary = "Replace database settings",
+            description = "Creates or replaces multiple Dataverse database settings from a JSON object.")
     @APIResponses({
         @APIResponse(responseCode = "200", description = "All database options successfully updated")
     })
-    public Response putAllSettings(JsonObject settings) {
+    public Response putAllSettings(@RequestBody(description = "JSON object whose keys are setting names and whose values are setting values.")
+            JsonObject settings) {
         try {
             // Basic JSON structure validation only
             if (settings == null || settings.isEmpty()) {
@@ -237,7 +248,12 @@ public Response putAllSettings(JsonObject settings) {
     
     @Path("settings/{name}")
     @PUT
-    public Response putSetting(@PathParam("name") String name, String content) {
+    @Operation(summary = "Store a database setting",
+            description = "Creates or replaces a Dataverse database setting value.")
+    public Response putSetting(@Parameter(description = "Database setting name.", required = true)
+            @PathParam("name") String name,
+            @RequestBody(description = "Setting value to store.")
+            String content) {
         try {
             SettingsServiceBean.validateSettingName(name);
             
@@ -250,7 +266,14 @@ public Response putSetting(@PathParam("name") String name, String content) {
 
     @Path("settings/{name}/lang/{lang}")
     @PUT
-    public Response putSettingLang(@PathParam("name") String name, @PathParam("lang") String lang, String content) {
+    @Operation(summary = "Store a localized database setting",
+            description = "Creates or replaces a language-specific Dataverse database setting value.")
+    public Response putSettingLang(@Parameter(description = "Database setting name.", required = true)
+            @PathParam("name") String name,
+            @Parameter(description = "Language code for the localized value.", required = true)
+            @PathParam("lang") String lang,
+            @RequestBody(description = "Localized setting value to store.")
+            String content) {
         try {
             SettingsServiceBean.validateSettingName(name);
             SettingsServiceBean.validateSettingLang(lang);
@@ -264,7 +287,11 @@ public Response putSettingLang(@PathParam("name") String name, @PathParam("lang"
 
     @Path("settings/{name}")
     @GET
-    public Response getSetting(@PathParam("name") String name) {
+    @Operation(operationId = "Admin_getSettingByName",
+            summary = "Read a database setting",
+            description = "Returns the value for a Dataverse database setting.")
+    public Response getSetting(@Parameter(description = "Database setting name.", required = true)
+            @PathParam("name") String name) {
         try {
             SettingsServiceBean.validateSettingName(name);
             
@@ -277,7 +304,13 @@ public Response getSetting(@PathParam("name") String name) {
     
     @Path("settings/{name}/lang/{lang}")
     @GET
-    public Response getSetting(@PathParam("name") String name, @PathParam("lang") String lang) {
+    @Operation(operationId = "Admin_getLocalizedSetting",
+            summary = "Read a localized database setting",
+            description = "Returns the language-specific value for a Dataverse database setting.")
+    public Response getSetting(@Parameter(description = "Database setting name.", required = true)
+            @PathParam("name") String name,
+            @Parameter(description = "Language code for the localized value.", required = true)
+            @PathParam("lang") String lang) {
         try {
             SettingsServiceBean.validateSettingName(name);
             SettingsServiceBean.validateSettingLang(lang);
@@ -291,7 +324,10 @@ public Response getSetting(@PathParam("name") String name, @PathParam("lang") St
 
     @Path("settings/{name}")
     @DELETE
-    public Response deleteSetting(@PathParam("name") String name) {
+    @Operation(summary = "Remove a database setting",
+            description = "Deletes a Dataverse database setting by name.")
+    public Response deleteSetting(@Parameter(description = "Database setting name.", required = true)
+            @PathParam("name") String name) {
         try {
             SettingsServiceBean.validateSettingName(name);
             
@@ -304,7 +340,12 @@ public Response deleteSetting(@PathParam("name") String name) {
 
     @Path("settings/{name}/lang/{lang}")
     @DELETE
-    public Response deleteSettingLang(@PathParam("name") String name, @PathParam("lang") String lang) {
+    @Operation(summary = "Remove a localized database setting",
+            description = "Deletes a language-specific Dataverse database setting value.")
+    public Response deleteSettingLang(@Parameter(description = "Database setting name.", required = true)
+            @PathParam("name") String name,
+            @Parameter(description = "Language code for the localized value.", required = true)
+            @PathParam("lang") String lang) {
         try {
             SettingsServiceBean.validateSettingName(name);
             SettingsServiceBean.validateSettingLang(lang);
@@ -318,7 +359,10 @@ public Response deleteSettingLang(@PathParam("name") String name, @PathParam("la
         
     @Path("template/{id}")
     @DELETE
-    public Response deleteTemplate(@PathParam("id") long id) {
+    @Operation(summary = "Remove a metadata template",
+            description = "Deletes a metadata template and clears default-template references that point to it.")
+    public Response deleteTemplate(@Parameter(description = "Template database id.", required = true)
+            @PathParam("id") long id) {
         
         AuthenticatedUser superuser = authSvc.getAdminUser();
         if (superuser == null) {
@@ -346,13 +390,18 @@ public Response deleteTemplate(@PathParam("id") long id) {
     
     @Path("templates")
     @GET
+    @Operation(summary = "Enumerate metadata templates",
+            description = "Lists metadata templates with template id, name, and owner information.")
     public Response findAllTemplates() {
         return findTemplates("");
     }
     
     @Path("templates/{alias}")
     @GET
-    public Response findTemplates(@PathParam("alias") String alias) {
+    @Operation(summary = "Enumerate metadata templates for a dataverse",
+            description = "Lists metadata templates owned by the dataverse with the supplied alias.")
+    public Response findTemplates(@Parameter(description = "Dataverse alias whose templates are listed.", required = true)
+            @PathParam("alias") String alias) {
         List<Template> templates;
 
             if (alias.isEmpty()) {
@@ -387,6 +436,8 @@ public Response findTemplates(@PathParam("alias") String alias) {
 
     @Path("authenticationProviderFactories")
     @GET
+    @Operation(summary = "Enumerate authentication provider factories",
+            description = "Lists authentication provider factory aliases and provider information.")
     public Response listAuthProviderFactories() {
         return ok(authSvc.listProviderFactories().stream()
                 .map(f -> jsonObjectBuilder().add("alias", f.getAlias()).add("info", f.getInfo()))
@@ -395,6 +446,8 @@ public Response listAuthProviderFactories() {
 
     @Path("authenticationProviders")
     @GET
+    @Operation(summary = "Enumerate authentication providers",
+            description = "Lists registered authentication provider rows.")
     public Response listAuthProviders() {
         return ok(em.createNamedQuery("AuthenticationProviderRow.findAll", AuthenticationProviderRow.class)
                 .getResultList().stream().map(r -> json(r)).collect(toJsonArray()));
@@ -402,7 +455,10 @@ public Response listAuthProviders() {
 
     @Path("authenticationProviders")
     @POST
-    public Response addProvider(AuthenticationProviderRow row) {
+    @Operation(summary = "Register an authentication provider",
+            description = "Creates or updates an authentication provider row and registers the provider when it is enabled.")
+    public Response addProvider(@RequestBody(description = "Authentication provider row, including id, factory alias, enabled state, and factory configuration.")
+            AuthenticationProviderRow row) {
         try {
             AuthenticationProviderRow managed = em.find(AuthenticationProviderRow.class, row.getId());
             if (managed != null) {
@@ -424,7 +480,10 @@ public Response addProvider(AuthenticationProviderRow row) {
 
     @Path("authenticationProviders/{id}")
     @GET
-    public Response showProvider(@PathParam("id") String id) {
+    @Operation(summary = "Read an authentication provider",
+            description = "Returns the registered authentication provider row for the supplied provider id.")
+    public Response showProvider(@Parameter(description = "Authentication provider id.", required = true)
+            @PathParam("id") String id) {
         AuthenticationProviderRow row = em.find(AuthenticationProviderRow.class, id);
         return (row != null) ? ok(json(row))
                 : error(Status.NOT_FOUND, "Can't find authetication provider with id '" + id + "'");
@@ -432,14 +491,24 @@ public Response showProvider(@PathParam("id") String id) {
 
     @POST
     @Path("authenticationProviders/{id}/:enabled")
-    public Response enableAuthenticationProvider_deprecated(@PathParam("id") String id, String body) {
+    @Operation(summary = "Set authentication provider enabled state through the deprecated route",
+            description = "Enables or disables an authentication provider using the legacy route.")
+    public Response enableAuthenticationProvider_deprecated(@Parameter(description = "Authentication provider id.", required = true)
+            @PathParam("id") String id,
+            @RequestBody(description = "Boolean value indicating whether the provider should be enabled.")
+            String body) {
         return enableAuthenticationProvider(id, body);
     }
 
     @PUT
     @Path("authenticationProviders/{id}/enabled")
     @Produces("application/json")
-    public Response enableAuthenticationProvider(@PathParam("id") String id, String body) {
+    @Operation(summary = "Switch authentication provider enabled state",
+            description = "Enables or disables a registered authentication provider.")
+    public Response enableAuthenticationProvider(@Parameter(description = "Authentication provider id.", required = true)
+            @PathParam("id") String id,
+            @RequestBody(description = "Boolean value indicating whether the provider should be enabled.")
+            String body) {
         body = body.trim();
         if (!Util.isBoolean(body)) {
             return error(Response.Status.BAD_REQUEST, "Illegal value '" + body + "'. Use 'true' or 'false'");
@@ -484,7 +553,10 @@ public Response enableAuthenticationProvider(@PathParam("id") String id, String
 
     @GET
     @Path("authenticationProviders/{id}/enabled")
-    public Response checkAuthenticationProviderEnabled(@PathParam("id") String id) {
+    @Operation(summary = "Check authentication provider enabled state",
+            description = "Returns whether a registered authentication provider is enabled.")
+    public Response checkAuthenticationProviderEnabled(@Parameter(description = "Authentication provider id.", required = true)
+            @PathParam("id") String id) {
         List<AuthenticationProviderRow> prvs = em
                 .createNamedQuery("AuthenticationProviderRow.findById", AuthenticationProviderRow.class)
                 .setParameter("id", id).getResultList();
@@ -497,7 +569,10 @@ public Response checkAuthenticationProviderEnabled(@PathParam("id") String id) {
 
     @DELETE
     @Path("authenticationProviders/{id}/")
-    public Response deleteAuthenticationProvider(@PathParam("id") String id) {
+    @Operation(summary = "Remove an authentication provider",
+            description = "Deletes an authentication provider row and deregisters the provider.")
+    public Response deleteAuthenticationProvider(@Parameter(description = "Authentication provider id.", required = true)
+            @PathParam("id") String id) {
         authProvidersRegistrationSvc.deregisterProvider(id);
         AuthenticationProviderRow row = em.find(AuthenticationProviderRow.class, id);
         if (row != null) {
@@ -512,7 +587,10 @@ public Response deleteAuthenticationProvider(@PathParam("id") String id) {
 
     @GET
     @Path("authenticatedUsers/{identifier}/")
-    public Response getAuthenticatedUserByIdentifier(@PathParam("identifier") String identifier) {
+    @Operation(summary = "Read an authenticated user",
+            description = "Returns account details for an authenticated user identifier.")
+    public Response getAuthenticatedUserByIdentifier(@Parameter(description = "Authenticated user identifier.", required = true)
+            @PathParam("identifier") String identifier) {
         AuthenticatedUser authenticatedUser = authSvc.getAuthenticatedUser(identifier);
         if (authenticatedUser != null) {
             return ok(json(authenticatedUser));
@@ -522,7 +600,10 @@ public Response getAuthenticatedUserByIdentifier(@PathParam("identifier") String
 
     @DELETE
     @Path("authenticatedUsers/{identifier}/")
-    public Response deleteAuthenticatedUser(@PathParam("identifier") String identifier) {
+    @Operation(summary = "Remove an authenticated user",
+            description = "Deletes an authenticated user after checking that the account can be safely removed.")
+    public Response deleteAuthenticatedUser(@Parameter(description = "Authenticated user identifier.", required = true)
+            @PathParam("identifier") String identifier) {
         AuthenticatedUser user = authSvc.getAuthenticatedUser(identifier);
         if (user != null) {
             return deleteAuthenticatedUser(user);
@@ -532,7 +613,10 @@ public Response deleteAuthenticatedUser(@PathParam("identifier") String identifi
     
     @DELETE
     @Path("authenticatedUsers/id/{id}/")
-    public Response deleteAuthenticatedUserById(@PathParam("id") Long id) {
+    @Operation(summary = "Remove an authenticated user by id",
+            description = "Deletes an authenticated user by database id after checking that the account can be safely removed.")
+    public Response deleteAuthenticatedUserById(@Parameter(description = "Authenticated user database id.", required = true)
+            @PathParam("id") Long id) {
         AuthenticatedUser user = authSvc.findByID(id);
         if (user != null) {
             return deleteAuthenticatedUser(user);
@@ -562,7 +646,10 @@ private Response deleteAuthenticatedUser(AuthenticatedUser au) {
 
     @POST
     @Path("authenticatedUsers/{identifier}/deactivate")
-    public Response deactivateAuthenticatedUser(@PathParam("identifier") String identifier) {
+    @Operation(summary = "Deactivate an authenticated user",
+            description = "Disables an authenticated user account by identifier.")
+    public Response deactivateAuthenticatedUser(@Parameter(description = "Authenticated user identifier.", required = true)
+            @PathParam("identifier") String identifier) {
         AuthenticatedUser user = authSvc.getAuthenticatedUser(identifier);
         if (user != null) {
             return deactivateAuthenticatedUser(user);
@@ -572,7 +659,10 @@ public Response deactivateAuthenticatedUser(@PathParam("identifier") String iden
 
     @POST
     @Path("authenticatedUsers/id/{id}/deactivate")
-    public Response deactivateAuthenticatedUserById(@PathParam("id") Long id) {
+    @Operation(summary = "Deactivate an authenticated user by id",
+            description = "Disables an authenticated user account by database id.")
+    public Response deactivateAuthenticatedUserById(@Parameter(description = "Authenticated user database id.", required = true)
+            @PathParam("id") Long id) {
         AuthenticatedUser user = authSvc.findByID(id);
         if (user != null) {
             return deactivateAuthenticatedUser(user);
@@ -595,7 +685,10 @@ private Response deactivateAuthenticatedUser(AuthenticatedUser userToDisable) {
 
     @POST
     @Path("publishDataverseAsCreator/{id}")
-    public Response publishDataverseAsCreator(@PathParam("id") long id) {
+    @Operation(summary = "Publish a dataverse as its creator",
+            description = "Publishes a dataverse using the dataverse creator as the request user.")
+    public Response publishDataverseAsCreator(@Parameter(description = "Dataverse database id.", required = true)
+            @PathParam("id") long id) {
         try {
             Dataverse dataverse = dataverseSvc.find(id);
             if (dataverse != null) {
@@ -614,6 +707,9 @@ public Response publishDataverseAsCreator(@PathParam("id") long id) {
     @GET
     @AuthRequired
     @Path("authenticatedUsers")
+    @Operation(summary = "Enumerate authenticated users",
+            description = "Lists all authenticated users for a superuser.")
+    @SecurityRequirement(name = "DataverseApiKey")
     public Response listAuthenticatedUsers(@Context ContainerRequestContext crc) {
         try {
             AuthenticatedUser user = getRequestAuthenticatedUserOrDie(crc);
@@ -634,11 +730,18 @@ public Response listAuthenticatedUsers(@Context ContainerRequestContext crc) {
     @AuthRequired
     @Path(listUsersPartialAPIPath)
     @Produces({ "application/json" })
+    @Operation(summary = "Search authenticated users",
+            description = "Searches authenticated users for the dashboard user list and returns paged JSON results.")
+    @SecurityRequirement(name = "DataverseApiKey")
     public Response filterAuthenticatedUsers(
             @Context ContainerRequestContext crc,
+            @Parameter(description = "Search text matched against authenticated users.")
             @QueryParam("searchTerm") String searchTerm,
+            @Parameter(description = "One-based result page to return.")
             @QueryParam("selectedPage") Integer selectedPage,
+            @Parameter(description = "Number of users to include on each page.")
             @QueryParam("itemsPerPage") Integer itemsPerPage,
+            @Parameter(description = "Sort field used for the user list.")
             @QueryParam("sortKey") String sortKey
     ) {
 
@@ -664,7 +767,10 @@ public Response filterAuthenticatedUsers(
      */
     @POST
     @Path("authenticatedUsers")
-    public Response createAuthenicatedUser(JsonObject jsonObject) {
+    @Operation(summary = "Provision an authenticated user",
+            description = "Creates an authenticated user account from provider id, persistent id, identifier, name, and email fields.")
+    public Response createAuthenicatedUser(@RequestBody(description = "User creation JSON containing authenticationProviderId, persistentUserId, identifier, firstName, lastName, and email.")
+            JsonObject jsonObject) {
         logger.fine("JSON in: " + jsonObject);
         String persistentUserId = jsonObject.getString("persistentUserId");
         String identifier = jsonObject.getString("identifier");
@@ -698,7 +804,14 @@ public Response createAuthenicatedUser(JsonObject jsonObject) {
     @AuthRequired
     @Path("authenticatedUsers/id/{id}/convertShibToBuiltIn")
     @Deprecated
-    public Response convertShibUserToBuiltin(@Context ContainerRequestContext crc, @PathParam("id") Long id, String newEmailAddress) {
+    @Operation(summary = "Convert a Shibboleth user to a built-in account",
+            description = "Converts a remote Shibboleth authenticated user to a built-in account using a new email address.")
+    @SecurityRequirement(name = "DataverseApiKey")
+    public Response convertShibUserToBuiltin(@Context ContainerRequestContext crc,
+            @Parameter(description = "Authenticated user database id.", required = true)
+            @PathParam("id") Long id,
+            @RequestBody(description = "Email address for the converted built-in account.")
+            String newEmailAddress) {
         try {
             AuthenticatedUser user = getRequestAuthenticatedUserOrDie(crc);
             if (!user.isSuperuser()) {
@@ -735,7 +848,14 @@ public Response convertShibUserToBuiltin(@Context ContainerRequestContext crc, @
     @PUT
     @AuthRequired
     @Path("authenticatedUsers/id/{id}/convertRemoteToBuiltIn")
-    public Response convertOAuthUserToBuiltin(@Context ContainerRequestContext crc, @PathParam("id") Long id, String newEmailAddress) {
+    @Operation(summary = "Convert a remote user to a built-in account",
+            description = "Converts a remote authenticated user to a built-in account using a new email address.")
+    @SecurityRequirement(name = "DataverseApiKey")
+    public Response convertOAuthUserToBuiltin(@Context ContainerRequestContext crc,
+            @Parameter(description = "Authenticated user database id.", required = true)
+            @PathParam("id") Long id,
+            @RequestBody(description = "Email address for the converted built-in account.")
+            String newEmailAddress) {
         try {
             AuthenticatedUser user = getRequestAuthenticatedUserOrDie(crc);
             if (!user.isSuperuser()) {
@@ -777,7 +897,12 @@ public Response convertOAuthUserToBuiltin(@Context ContainerRequestContext crc,
     @PUT
     @AuthRequired
     @Path("authenticatedUsers/convert/builtin2shib")
-    public Response builtin2shib(@Context ContainerRequestContext crc, String content) {
+    @Operation(summary = "Convert a built-in user to a Shibboleth account",
+            description = "Converts a built-in authenticated user to a Shibboleth account using colon-separated conversion data.")
+    @SecurityRequirement(name = "DataverseApiKey")
+    public Response builtin2shib(@Context ContainerRequestContext crc,
+            @RequestBody(description = "Colon-separated email, password, and replacement email values for the conversion.")
+            String content) {
         logger.info("entering builtin2shib...");
         try {
             AuthenticatedUser userToRunThisMethod = getRequestAuthenticatedUserOrDie(crc);
@@ -928,7 +1053,12 @@ public Response builtin2shib(@Context ContainerRequestContext crc, String conten
     @PUT
     @AuthRequired
     @Path("authenticatedUsers/convert/builtin2oauth")
-    public Response builtin2oauth(@Context ContainerRequestContext crc, String content) {
+    @Operation(summary = "Convert a built-in user to a remote account",
+            description = "Converts a built-in authenticated user to a remote account using colon-separated conversion data.")
+    @SecurityRequirement(name = "DataverseApiKey")
+    public Response builtin2oauth(@Context ContainerRequestContext crc,
+            @RequestBody(description = "Colon-separated email, password, replacement email, provider id, and persistent user id values.")
+            String content) {
         logger.info("entering builtin2oauth...");
         try {
             AuthenticatedUser userToRunThisMethod = getRequestAuthenticatedUserOrDie(crc);
@@ -1081,7 +1211,10 @@ public Response builtin2oauth(@Context ContainerRequestContext crc, String conte
 
     @Path("roles")
     @POST
-    public Response createNewBuiltinRole(RoleDTO roleDto) {
+    @Operation(summary = "Provision a built-in role",
+            description = "Creates a built-in Dataverse role from the supplied role definition.")
+    public Response createNewBuiltinRole(@RequestBody(description = "Role definition containing alias, name, description, and permissions.")
+            RoleDTO roleDto) {
         ActionLogRecord alr = new ActionLogRecord(ActionLogRecord.ActionType.Admin, "createBuiltInRole")
                 .setInfo(roleDto.getAlias() + ":" + roleDto.getDescription());
         try {
@@ -1096,7 +1229,12 @@ public Response createNewBuiltinRole(RoleDTO roleDto) {
     }
     @Path("roles/{id}")
     @PUT
-    public Response updateBuiltinRole(RoleDTO roleDto, @PathParam("id") long roleId) {
+    @Operation(summary = "Revise a built-in role",
+            description = "Updates an existing built-in Dataverse role from the supplied role definition.")
+    public Response updateBuiltinRole(@RequestBody(description = "Updated role definition containing alias, name, description, and permissions.")
+            RoleDTO roleDto,
+            @Parameter(description = "Role database id.", required = true)
+            @PathParam("id") long roleId) {
         ActionLogRecord alr = new ActionLogRecord(ActionLogRecord.ActionType.Admin, "updateBuiltInRole")
                 .setInfo(roleDto.getAlias() + ":" + roleDto.getDescription());
         try {
@@ -1113,6 +1251,8 @@ public Response updateBuiltinRole(RoleDTO roleDto, @PathParam("id") long roleId)
 
     @Path("roles")
     @GET
+    @Operation(summary = "Enumerate built-in roles",
+            description = "Lists built-in Dataverse roles.")
     public Response listBuiltinRoles() {
         try {
             return ok(rolesToJson(rolesSvc.findBuiltinRoles()));
@@ -1124,7 +1264,12 @@ public Response listBuiltinRoles() {
     @DELETE
     @AuthRequired
     @Path("roles/{id}")
-    public Response deleteRole(@Context ContainerRequestContext crc, @PathParam("id") String id) {
+    @Operation(summary = "Remove a built-in role",
+            description = "Deletes a Dataverse role by id or alias.")
+    @SecurityRequirement(name = "DataverseApiKey")
+    public Response deleteRole(@Context ContainerRequestContext crc,
+            @Parameter(description = "Role id or alias.", required = true)
+            @PathParam("id") String id) {
 
         return response(req -> {
             DataverseRole doomed = findRoleOrDie(id);
@@ -1136,7 +1281,10 @@ public Response deleteRole(@Context ContainerRequestContext crc, @PathParam("id"
     @Path("superuser/{identifier}")
     @Deprecated
     @POST
-    public Response toggleSuperuser(@PathParam("identifier") String identifier) {
+    @Operation(summary = "Toggle superuser status",
+            description = "Switches an authenticated user between superuser and non-superuser status.")
+    public Response toggleSuperuser(@Parameter(description = "Authenticated user identifier.", required = true)
+            @PathParam("identifier") String identifier) {
         ActionLogRecord alr = new ActionLogRecord(ActionLogRecord.ActionType.Admin, "toggleSuperuser")
                 .setInfo(identifier);
         try {
@@ -1163,7 +1311,12 @@ private Response setSuperuserStatus(AuthenticatedUser user, Boolean isSuperuser)
     @Path("superuser/{identifier}")
     @PUT
     // Using string instead of boolean so user doesn't need to add a Content-type header in their request
-    public Response setSuperuserStatus(@PathParam("identifier") String identifier, String isSuperuser) {
+    @Operation(summary = "Assign superuser status",
+            description = "Sets whether an authenticated user has superuser privileges.")
+    public Response setSuperuserStatus(@Parameter(description = "Authenticated user identifier.", required = true)
+            @PathParam("identifier") String identifier,
+            @RequestBody(description = "Boolean text indicating whether the user should be a superuser.")
+            String isSuperuser) {
         ActionLogRecord alr = new ActionLogRecord(ActionLogRecord.ActionType.Admin, "setSuperuserStatus")
                 .setInfo(identifier + ":" + isSuperuser);
         try {
@@ -1180,7 +1333,10 @@ public Response setSuperuserStatus(@PathParam("identifier") String identifier, S
     @GET
     @Path("validate/datasets")
     @Produces({"application/json"})
-    public Response validateAllDatasets(@QueryParam("variables") boolean includeVariables) {
+    @Operation(summary = "Validate all datasets",
+            description = "Streams validation results for every local dataset.")
+    public Response validateAllDatasets(@Parameter(description = "Whether to include variable-level validation details.")
+            @QueryParam("variables") boolean includeVariables) {
         
         // Streaming output: the API will start producing 
         // the output right away, as it goes through the list 
@@ -1273,7 +1429,12 @@ public void write(OutputStream os) throws IOException,
         
     @Path("validate/dataset/{id}")
     @GET
-    public Response validateDataset(@PathParam("id") String id, @QueryParam("variables") boolean includeVariables) {
+    @Operation(summary = "Validate one dataset",
+            description = "Validates a dataset and returns either valid status or the first constraint violation.")
+    public Response validateDataset(@Parameter(description = "Dataset id or persistent identifier.", required = true)
+            @PathParam("id") String id,
+            @Parameter(description = "Whether to include variable-level validation details.")
+            @QueryParam("variables") boolean includeVariables) {
         Dataset dataset;
         try {
             dataset = findDatasetOrDie(id);
@@ -1318,7 +1479,10 @@ public Response validateDataset(@PathParam("id") String id, @QueryParam("variabl
     @GET
     @Path("validate/dataset/files/{id}")
     @Produces({"application/json"})
-    public Response validateDatasetDatafiles(@PathParam("id") String id) {
+    @Operation(summary = "Validate files in one dataset",
+            description = "Streams checksum validation results for all data files in a dataset.")
+    public Response validateDatasetDatafiles(@Parameter(description = "Dataset id or persistent identifier.", required = true)
+            @PathParam("id") String id) {
         
         Dataset dataset;
         // First check if the dataset exists before starting the streaming output
@@ -1384,7 +1548,10 @@ public void write(OutputStream os) throws IOException,
 
     @Path("assignments/assignees/{raIdtf: .*}")
     @GET
-    public Response getAssignmentsFor(@PathParam("raIdtf") String raIdtf) {
+    @Operation(summary = "Enumerate assignments for a role assignee",
+            description = "Lists role assignments held by the supplied role assignee identifier.")
+    public Response getAssignmentsFor(@Parameter(description = "Role assignee identifier.", required = true)
+            @PathParam("raIdtf") String raIdtf) {
 
         JsonArrayBuilder arr = Json.createArrayBuilder();
         roleAssigneeSvc.getAssignmentsFor(raIdtf).forEach(a -> arr.add(json(a)));
@@ -1401,7 +1568,10 @@ public Response getAssignmentsFor(@PathParam("raIdtf") String raIdtf) {
      */
     @Path("confirmEmail/{userId}")
     @GET
-    public Response getConfirmEmailToken(@PathParam("userId") long userId) {
+    @Operation(summary = "Read a confirm-email token",
+            description = "Returns the active confirm-email token for an authenticated user.")
+    public Response getConfirmEmailToken(@Parameter(description = "Authenticated user database id.", required = true)
+            @PathParam("userId") long userId) {
         AuthenticatedUser user = authSvc.findByID(userId);
         if (user != null) {
             ConfirmEmailData confirmEmailData = confirmEmailSvc.findSingleConfirmEmailDataByUser(user);
@@ -1420,7 +1590,10 @@ public Response getConfirmEmailToken(@PathParam("userId") long userId) {
      */
     @Path("confirmEmail/{userId}")
     @POST
-    public Response startConfirmEmailProcess(@PathParam("userId") long userId) {
+    @Operation(summary = "Start confirm-email processing",
+            description = "Creates confirm-email data for an authenticated user and returns token metadata.")
+    public Response startConfirmEmailProcess(@Parameter(description = "Authenticated user database id.", required = true)
+            @PathParam("userId") long userId) {
         AuthenticatedUser user = authSvc.findByID(userId);
         if (user != null) {
             try {
@@ -1442,7 +1615,10 @@ public Response startConfirmEmailProcess(@PathParam("userId") long userId) {
      */
     @Path("convertUserFromBcryptToSha1")
     @POST
-    public Response convertUserFromBcryptToSha1(String json) {
+    @Operation(summary = "Convert a test built-in password hash",
+            description = "Rewrites a built-in user's password hash to the legacy SHA-1 test value.")
+    public Response convertUserFromBcryptToSha1(@RequestBody(description = "JSON object containing builtinUserId.")
+            String json) {
         JsonReader jsonReader = Json.createReader(new StringReader(json));
         JsonObject object = jsonReader.readObject();
         jsonReader.close();
@@ -1457,7 +1633,12 @@ public Response convertUserFromBcryptToSha1(String json) {
     @Path("permissions/{dvo}")
     @AuthRequired
     @GET
-    public Response findPermissonsOn(@Context final ContainerRequestContext crc, @PathParam("dvo") final String dvo) {
+    @Operation(summary = "Inspect permissions on a Dataverse object",
+            description = "Returns the requesting user's permissions on the selected dataverse object.")
+    @SecurityRequirement(name = "DataverseApiKey")
+    public Response findPermissonsOn(@Context final ContainerRequestContext crc,
+            @Parameter(description = "Dataverse object id or persistent identifier.", required = true)
+            @PathParam("dvo") final String dvo) {
         try {
             final DvObject dvObj = findDvo(dvo);
             final User aUser = getRequestUser(crc);
@@ -1475,14 +1656,21 @@ public Response findPermissonsOn(@Context final ContainerRequestContext crc, @Pa
 
     @Path("assignee/{idtf}")
     @GET
-    public Response findRoleAssignee(@PathParam("idtf") String idtf) {
+    @Operation(summary = "Read a role assignee",
+            description = "Returns display information for a role assignee identifier.")
+    public Response findRoleAssignee(@Parameter(description = "Role assignee identifier.", required = true)
+            @PathParam("idtf") String idtf) {
         RoleAssignee ra = roleAssigneeSvc.getRoleAssignee(idtf);
         return (ra == null) ? notFound("Role Assignee '" + idtf + "' not found.") : ok(json(ra.getDisplayInfo()));
     }
 
     @Path("datasets/integrity/{datasetVersionId}/fixmissingunf")
     @POST
-    public Response fixUnf(@PathParam("datasetVersionId") String datasetVersionId,
+    @Operation(summary = "Repair missing UNF values",
+            description = "Recalculates missing UNF values for a dataset version.")
+    public Response fixUnf(@Parameter(description = "Dataset version database id.", required = true)
+            @PathParam("datasetVersionId") String datasetVersionId,
+            @Parameter(description = "When true, recalculate UNF values even when existing values are present.")
             @QueryParam("forceRecalculate") boolean forceRecalculate) {
         JsonObjectBuilder info = datasetVersionSvc.fixMissingUnf(datasetVersionId, forceRecalculate);
         return ok(info);
@@ -1490,6 +1678,8 @@ public Response fixUnf(@PathParam("datasetVersionId") String datasetVersionId,
 
     @Path("datafiles/integrity/fixmissingoriginaltypes")
     @GET
+    @Operation(summary = "Repair missing original file types",
+            description = "Starts a background repair for tabular files missing original file type metadata.")
     public Response fixMissingOriginalTypes() {
         JsonObjectBuilder info = Json.createObjectBuilder();
 
@@ -1513,7 +1703,10 @@ public Response fixMissingOriginalTypes() {
         
     @Path("datafiles/integrity/fixmissingoriginalsizes")
     @GET
-    public Response fixMissingOriginalSizes(@QueryParam("limit") Integer limit) {
+    @Operation(summary = "Repair missing original file sizes",
+            description = "Starts a background repair for tabular files missing original file size metadata.")
+    public Response fixMissingOriginalSizes(@Parameter(description = "Maximum number of affected files to repair.")
+            @QueryParam("limit") Integer limit) {
         JsonObjectBuilder info = Json.createObjectBuilder();
 
         List<Long> affectedFileIds = fileService.selectFilesWithMissingOriginalSizes();
@@ -1544,7 +1737,10 @@ public Response fixMissingOriginalSizes(@QueryParam("limit") Integer limit) {
      */
     @GET
     @Path("datasets/thumbnailMetadata/{id}")
-    public Response getDatasetThumbnailMetadata(@PathParam("id") Long idSupplied) {
+    @Operation(summary = "Read dataset thumbnail metadata",
+            description = "Returns thumbnail selection metadata and optional thumbnail image data for a dataset.")
+    public Response getDatasetThumbnailMetadata(@Parameter(description = "Dataset database id.", required = true)
+            @PathParam("id") Long idSupplied) {
         Dataset dataset = datasetSvc.find(idSupplied);
         if (dataset == null) {
             return error(Response.Status.NOT_FOUND, "Could not find dataset based on id supplied: " + idSupplied + ".");
@@ -1577,7 +1773,10 @@ public Response getDatasetThumbnailMetadata(@PathParam("id") Long idSupplied) {
      */
     @Path("validatePassword")
     @POST
-    public Response validatePassword(String password) {
+    @Operation(summary = "Validate a password",
+            description = "Checks a password against the configured password policy and returns validation errors.")
+    public Response validatePassword(@RequestBody(description = "Password text to validate.")
+            String password) {
 
         final List<String> errors = passwordValidatorService.validate(password, new Date(), false);
         final JsonArrayBuilder errorArray = Json.createArrayBuilder();
@@ -1587,6 +1786,8 @@ public Response validatePassword(String password) {
 
     @GET
     @Path("/isOrcid")
+    @Operation(summary = "Check ORCID authentication support",
+            description = "Returns whether ORCID authentication is enabled.")
     public Response isOrcidEnabled() {
         return authSvc.isOrcidEnabled() ? ok("Orcid is enabled") : ok("no orcid for you.");
     }
@@ -1594,7 +1795,12 @@ public Response isOrcidEnabled() {
     @POST
     @AuthRequired
     @Path("{id}/reregisterHDLToPID")
-    public Response reregisterHdlToPID(@Context ContainerRequestContext crc, @PathParam("id") String id) {
+    @Operation(summary = "Migrate a dataset handle registration to DOI",
+            description = "Registers a dataset PID again when migrating a released handle-based dataset to DOI.")
+    @SecurityRequirement(name = "DataverseApiKey")
+    public Response reregisterHdlToPID(@Context ContainerRequestContext crc,
+            @Parameter(description = "Dataset id or persistent identifier.", required = true)
+            @PathParam("id") String id) {
         logger.info("Starting to reregister  " + id + " Dataset Id. (from hdl to doi)" + new Date());
         try {
 
@@ -1633,7 +1839,12 @@ public Response reregisterHdlToPID(@Context ContainerRequestContext crc, @PathPa
     @GET
     @AuthRequired
     @Path("{id}/registerDataFile")
-    public Response registerDataFile(@Context ContainerRequestContext crc, @PathParam("id") String id) {
+    @Operation(summary = "Process PID assignment for a data file",
+            description = "Attempts persistent identifier assignment for one published data file when file PIDs are enabled.")
+    @SecurityRequirement(name = "DataverseApiKey")
+    public Response registerDataFile(@Context ContainerRequestContext crc,
+            @Parameter(description = "Data file id or persistent identifier.", required = true)
+            @PathParam("id") String id) {
         logger.info("Starting to register  " + id + " file id. " + new Date());
 
         try {
@@ -1660,6 +1871,9 @@ public Response registerDataFile(@Context ContainerRequestContext crc, @PathPara
     @GET
     @AuthRequired
     @Path("/registerDataFileAll")
+    @Operation(summary = "Process PID assignment for all eligible data files",
+            description = "Scans all data files and assigns persistent identifiers to released, unregistered files in collections where file PIDs are enabled.")
+    @SecurityRequirement(name = "DataverseApiKey")
     public Response registerDataFileAll(@Context ContainerRequestContext crc) {
         Integer count = fileService.findAll().size();
         Integer successes = 0;
@@ -1732,7 +1946,14 @@ public Response registerDataFileAll(@Context ContainerRequestContext crc) {
     @GET
     @AuthRequired
     @Path("/registerDataFiles/{alias}")
-    public Response registerDataFilesInCollection(@Context ContainerRequestContext crc, @PathParam("alias") String alias, @QueryParam("sleep") Integer sleepInterval) {
+    @Operation(summary = "Process PID assignment for collection data files",
+            description = "Assigns persistent identifiers to released, unregistered files directly owned by a collection.")
+    @SecurityRequirement(name = "DataverseApiKey")
+    public Response registerDataFilesInCollection(@Context ContainerRequestContext crc,
+            @Parameter(description = "Dataverse alias for the collection whose files are processed.", required = true)
+            @PathParam("alias") String alias,
+            @Parameter(description = "Seconds to wait between file registration attempts.")
+            @QueryParam("sleep") Integer sleepInterval) {
         Dataverse collection;
         try {
             collection = findDataverseOrDie(alias);
@@ -1925,7 +2146,14 @@ public Response updateHashValues(@Context ContainerRequestContext crc, @PathPara
     @POST
     @AuthRequired
     @Path("/computeDataFileHashValue/{fileId}/algorithm/{alg}")
-    public Response computeDataFileHashValue(@Context ContainerRequestContext crc, @PathParam("fileId") String fileId, @PathParam("alg") String alg) {
+    @Operation(summary = "Compute a data file hash value",
+            description = "Calculates a new checksum for one non-harvested data file using the requested algorithm and saves it on the file.")
+    @SecurityRequirement(name = "DataverseApiKey")
+    public Response computeDataFileHashValue(@Context ContainerRequestContext crc,
+            @Parameter(description = "Data file id or persistent identifier.", required = true)
+            @PathParam("fileId") String fileId,
+            @Parameter(description = "Checksum algorithm to calculate.", required = true)
+            @PathParam("alg") String alg) {
 
         try {
             User u = getRequestAuthenticatedUserOrDie(crc);
@@ -1987,7 +2215,12 @@ public Response computeDataFileHashValue(@Context ContainerRequestContext crc, @
     @POST
     @AuthRequired
     @Path("/validateDataFileHashValue/{fileId}")
-    public Response validateDataFileHashValue(@Context ContainerRequestContext crc, @PathParam("fileId") String fileId) {
+    @Operation(summary = "Validate a data file hash value",
+            description = "Recalculates a data file checksum and compares it with the stored checksum.")
+    @SecurityRequirement(name = "DataverseApiKey")
+    public Response validateDataFileHashValue(@Context ContainerRequestContext crc,
+            @Parameter(description = "Data file id or persistent identifier.", required = true)
+            @PathParam("fileId") String fileId) {
 
         try {
             User u = getRequestAuthenticatedUserOrDie(crc);
@@ -2054,7 +2287,13 @@ public Response validateDataFileHashValue(@Context ContainerRequestContext crc,
     @POST
     @AuthRequired
     @Path("/submitDatasetVersionToArchive/{id}/{version}")
-    public Response submitDatasetVersionToArchive(@Context ContainerRequestContext crc, @PathParam("id") String dsid,
+    @Operation(summary = "Submit a dataset version to an archive",
+            description = "Starts archival submission for a dataset version that has not already been archived.")
+    @SecurityRequirement(name = "DataverseApiKey")
+    public Response submitDatasetVersionToArchive(@Context ContainerRequestContext crc,
+            @Parameter(description = "Dataset id or persistent identifier.", required = true)
+            @PathParam("id") String dsid,
+            @Parameter(description = "Dataset version number.", required = true)
             @PathParam("version") String versionNumber) {
 
         try {
@@ -2128,7 +2367,16 @@ public void run() {
     @POST
     @AuthRequired
     @Path("/archiveAllUnarchivedDatasetVersions")
-    public Response archiveAllUnarchivedDatasetVersions(@Context ContainerRequestContext crc, @QueryParam("listonly") boolean listonly, @QueryParam("limit") Integer limit, @QueryParam("latestonly") boolean latestonly) {
+    @Operation(summary = "Archive unarchived dataset versions",
+            description = "Lists or starts archival submission for published dataset versions that do not yet have archival copies.")
+    @SecurityRequirement(name = "DataverseApiKey")
+    public Response archiveAllUnarchivedDatasetVersions(@Context ContainerRequestContext crc,
+            @Parameter(description = "When true, list matching dataset versions without submitting them.")
+            @QueryParam("listonly") boolean listonly,
+            @Parameter(description = "Maximum number of dataset versions to list or submit.")
+            @QueryParam("limit") Integer limit,
+            @Parameter(description = "When true, include only each dataset's latest version for archival submission.")
+            @QueryParam("latestonly") boolean latestonly) {
 
         try {
             AuthenticatedUser au = getRequestAuthenticatedUserOrDie(crc);
@@ -2210,6 +2458,8 @@ public void run() {
     
     @DELETE
     @Path("/clearMetricsCache")
+    @Operation(summary = "Clear all metrics cache entries",
+            description = "Deletes every cached metric row.")
     public Response clearMetricsCache() {
         em.createNativeQuery("DELETE FROM metric").executeUpdate();
         return ok("all metric caches cleared.");
@@ -2217,7 +2467,10 @@ public Response clearMetricsCache() {
 
     @DELETE
     @Path("/clearMetricsCache/{name}")
-    public Response clearMetricsCacheByName(@PathParam("name") String name) {
+    @Operation(summary = "Clear metrics cache entries by name",
+            description = "Deletes cached metric rows with the supplied metric name.")
+    public Response clearMetricsCacheByName(@Parameter(description = "Metric cache name to clear.", required = true)
+            @PathParam("name") String name) {
         Query deleteQuery = em.createNativeQuery("DELETE FROM metric where name = ?");
         deleteQuery.setParameter(1, name);
         deleteQuery.executeUpdate();
@@ -2227,7 +2480,12 @@ public Response clearMetricsCacheByName(@PathParam("name") String name) {
     @GET
     @AuthRequired
     @Path("/dataverse/{alias}/addRoleAssignmentsToChildren")
-    public Response addRoleAssignementsToChildren(@Context ContainerRequestContext crc, @PathParam("alias") String alias) throws WrappedResponse {
+    @Operation(summary = "Propagate dataverse role assignments to children",
+            description = "Copies configured inherited role assignments from a dataverse to its child dataverses and datasets.")
+    @SecurityRequirement(name = "DataverseApiKey")
+    public Response addRoleAssignementsToChildren(@Context ContainerRequestContext crc,
+            @Parameter(description = "Dataverse alias whose child objects receive role assignments.", required = true)
+            @PathParam("alias") String alias) throws WrappedResponse {
         Dataverse owner = dataverseSvc.findByAlias(alias);
         if (owner == null) {
             return error(Response.Status.NOT_FOUND, "Could not find dataverse based on alias supplied: " + alias + ".");
@@ -2281,7 +2539,14 @@ public Response getCurationLabelSet(@Context ContainerRequestContext crc, @PathP
     @PUT
     @AuthRequired
     @Path("/dataverse/{alias}/curationLabelSet")
-    public Response setCurationLabelSet(@Context ContainerRequestContext crc, @PathParam("alias") String alias, @QueryParam("name") String name) throws WrappedResponse {
+    @Operation(summary = "Assign a dataverse curation label set",
+            description = "Assigns a configured curation label set name to a dataverse.")
+    @SecurityRequirement(name = "DataverseApiKey")
+    public Response setCurationLabelSet(@Context ContainerRequestContext crc,
+            @Parameter(description = "Dataverse alias.", required = true)
+            @PathParam("alias") String alias,
+            @Parameter(description = "Configured curation label set name.")
+            @QueryParam("name") String name) throws WrappedResponse {
         Dataverse dataverse = dataverseSvc.findByAlias(alias);
         if (dataverse == null) {
             return error(Response.Status.NOT_FOUND, "Could not find dataverse based on alias supplied: " + alias + ".");
@@ -2312,7 +2577,12 @@ public Response setCurationLabelSet(@Context ContainerRequestContext crc, @PathP
     @DELETE
     @AuthRequired
     @Path("/dataverse/{alias}/curationLabelSet")
-    public Response resetCurationLabelSet(@Context ContainerRequestContext crc, @PathParam("alias") String alias) throws WrappedResponse {
+    @Operation(summary = "Reset a dataverse curation label set",
+            description = "Restores a dataverse to the default curation label set setting.")
+    @SecurityRequirement(name = "DataverseApiKey")
+    public Response resetCurationLabelSet(@Context ContainerRequestContext crc,
+            @Parameter(description = "Dataverse alias.", required = true)
+            @PathParam("alias") String alias) throws WrappedResponse {
         Dataverse dataverse = dataverseSvc.findByAlias(alias);
         if (dataverse == null) {
             return error(Response.Status.NOT_FOUND, "Could not find dataverse based on alias supplied: " + alias + ".");
@@ -2332,6 +2602,9 @@ public Response resetCurationLabelSet(@Context ContainerRequestContext crc, @Pat
     @GET
     @AuthRequired
     @Path("/dataverse/curationLabelSets")
+    @Operation(summary = "Enumerate curation label sets",
+            description = "Lists configured curation label sets and their labels.")
+    @SecurityRequirement(name = "DataverseApiKey")
     public Response listCurationLabelSets(@Context ContainerRequestContext crc) throws WrappedResponse {
         try {
             AuthenticatedUser user = getRequestAuthenticatedUserOrDie(crc);
@@ -2353,7 +2626,10 @@ public Response listCurationLabelSets(@Context ContainerRequestContext crc) thro
     
     @POST
     @Path("/bannerMessage")
-    public Response addBannerMessage(JsonObject jsonObject) throws WrappedResponse {
+    @Operation(summary = "Publish a banner message",
+            description = "Creates an active banner message with localized message text.")
+    public Response addBannerMessage(@RequestBody(description = "Banner message JSON containing dismissibleByUser and messageTexts entries.")
+            JsonObject jsonObject) throws WrappedResponse {
 
         BannerMessage toAdd = new BannerMessage();
         try {
@@ -2395,7 +2671,10 @@ public Response addBannerMessage(JsonObject jsonObject) throws WrappedResponse {
     
     @DELETE
     @Path("/bannerMessage/{id}")
-    public Response deleteBannerMessage(@PathParam("id") Long id) throws WrappedResponse {
+    @Operation(summary = "Remove a banner message",
+            description = "Deletes a banner message by database id.")
+    public Response deleteBannerMessage(@Parameter(description = "Banner message database id.", required = true)
+            @PathParam("id") Long id) throws WrappedResponse {
  
         BannerMessage message = em.find(BannerMessage.class, id);
         if (message == null){
@@ -2409,7 +2688,10 @@ public Response deleteBannerMessage(@PathParam("id") Long id) throws WrappedResp
     
     @PUT
     @Path("/bannerMessage/{id}/deactivate")
-    public Response deactivateBannerMessage(@PathParam("id") Long id) throws WrappedResponse {
+    @Operation(summary = "Deactivate a banner message",
+            description = "Marks a banner message inactive by database id.")
+    public Response deactivateBannerMessage(@Parameter(description = "Banner message database id.", required = true)
+            @PathParam("id") Long id) throws WrappedResponse {
         BannerMessage message = em.find(BannerMessage.class, id);
         if (message == null){
             return error(Response.Status.NOT_FOUND, "Message id = "  + id + " not found.");
@@ -2422,7 +2704,10 @@ public Response deactivateBannerMessage(@PathParam("id") Long id) throws Wrapped
     
     @GET
     @Path("/bannerMessage")
-    public Response getBannerMessages(@PathParam("id") Long id) throws WrappedResponse {
+    @Operation(summary = "Enumerate banner messages",
+            description = "Lists banner message ids and display values.")
+    public Response getBannerMessages(@Parameter(description = "Unused banner message id parameter.")
+            @PathParam("id") Long id) throws WrappedResponse {
 
         List<BannerMessage> messagesList = bannerMessageService.findAllBannerMessages();
 
@@ -2443,7 +2728,12 @@ public Response getBannerMessages(@PathParam("id") Long id) throws WrappedRespon
     @AuthRequired
     @Consumes("application/json")
     @Path("/requestSignedUrl")
-    public Response getSignedUrl(@Context ContainerRequestContext crc, JsonObject urlInfo) {
+    @Operation(summary = "Sign a URL",
+            description = "Creates a signed URL for a supplied URL and optional user token context.")
+    @SecurityRequirement(name = "DataverseApiKey")
+    public Response getSignedUrl(@Context ContainerRequestContext crc,
+            @RequestBody(description = "JSON object containing url, optional user identifier, timeout, HTTP method, and optional credential key.")
+            JsonObject urlInfo) {
         AuthenticatedUser superuser = null;
         try {
             superuser = getRequestAuthenticatedUserOrDie(crc);
@@ -2489,6 +2779,8 @@ public Response getSignedUrl(@Context ContainerRequestContext crc, JsonObject ur
  
     @DELETE
     @Path("/clearThumbnailFailureFlag")
+    @Operation(summary = "Clear all thumbnail failure flags",
+            description = "Resets thumbnail preview failure flags for all dataverse objects.")
     public Response clearThumbnailFailureFlag() {
         em.createNativeQuery("UPDATE dvobject SET previewimagefail = FALSE").executeUpdate();
         return ok("Thumbnail Failure Flags cleared.");
@@ -2496,7 +2788,10 @@ public Response clearThumbnailFailureFlag() {
     
     @DELETE
     @Path("/clearThumbnailFailureFlag/{id}")
-    public Response clearThumbnailFailureFlagByDatafile(@PathParam("id") String fileId) {
+    @Operation(summary = "Clear a data file thumbnail failure flag",
+            description = "Resets the thumbnail preview failure flag for one data file.")
+    public Response clearThumbnailFailureFlagByDatafile(@Parameter(description = "Data file id or persistent identifier.", required = true)
+            @PathParam("id") String fileId) {
         try {
             DataFile df = findDataFileOrDie(fileId);
             Query deleteQuery = em.createNativeQuery("UPDATE dvobject SET previewimagefail = FALSE where id = ?");
@@ -2515,7 +2810,12 @@ public Response clearThumbnailFailureFlagByDatafile(@PathParam("id") String file
     @GET
     @AuthRequired
     @Path("/downloadTmpFile")
-    public Response downloadTmpFile(@Context ContainerRequestContext crc, @QueryParam("fullyQualifiedPathToFile") String fullyQualifiedPathToFile) {
+    @Operation(summary = "Download a temporary file",
+            description = "Streams a file from the local /tmp directory for superuser testing.")
+    @SecurityRequirement(name = "DataverseApiKey")
+    public Response downloadTmpFile(@Context ContainerRequestContext crc,
+            @Parameter(description = "Absolute path under /tmp to stream.")
+            @QueryParam("fullyQualifiedPathToFile") String fullyQualifiedPathToFile) {
         try {
             AuthenticatedUser user = getRequestAuthenticatedUserOrDie(crc);
             if (!user.isSuperuser()) {
@@ -2537,6 +2837,8 @@ public Response downloadTmpFile(@Context ContainerRequestContext crc, @QueryPara
 
     @GET
     @Path("/featureFlags")
+    @Operation(summary = "Enumerate feature flags",
+            description = "Lists feature flag names with enabled or disabled status.")
     public Response getFeatureFlags() {
         Map<String, String> map = new TreeMap<>();
         for (FeatureFlags flag : FeatureFlags.values()) {
@@ -2547,7 +2849,10 @@ public Response getFeatureFlags() {
 
     @GET
     @Path("/featureFlags/{flag}")
-    public Response getFeatureFlag(@PathParam("flag") String flagIn) {
+    @Operation(summary = "Read a feature flag",
+            description = "Returns enabled status for one feature flag.")
+    public Response getFeatureFlag(@Parameter(description = "Feature flag enum name.", required = true)
+            @PathParam("flag") String flagIn) {
         try {
             FeatureFlags flag = FeatureFlags.valueOf(flagIn);
             JsonObjectBuilder job = Json.createObjectBuilder();
@@ -2561,8 +2866,15 @@ public Response getFeatureFlag(@PathParam("flag") String flagIn) {
     @GET
     @AuthRequired
     @Path("/datafiles/auditFiles")
+    @Operation(summary = "Audit dataset file storage",
+            description = "Checks selected datasets for missing physical files and missing file metadata.")
+    @SecurityRequirement(name = "DataverseApiKey")
     public Response getAuditFiles(@Context ContainerRequestContext crc,
-                                  @QueryParam("firstId") Long firstId, @QueryParam("lastId") Long lastId,
+                                  @Parameter(description = "Lowest dataset database id to audit.")
+                                  @QueryParam("firstId") Long firstId,
+                                  @Parameter(description = "Highest dataset database id to audit.")
+                                  @QueryParam("lastId") Long lastId,
+                                  @Parameter(description = "Comma-separated dataset persistent identifiers to audit instead of an id range.")
                                   @QueryParam("datasetIdentifierList") String datasetIdentifierList) throws WrappedResponse {
         try {
             AuthenticatedUser user = getRequestAuthenticatedUserOrDie(crc);
@@ -2719,7 +3031,11 @@ public Response getAuditFiles(@Context ContainerRequestContext crc,
     @AuthRequired
     @Path("/rateLimitStats")
     @Produces("text/csv")
+    @Operation(summary = "Download rate-limit statistics",
+            description = "Streams cached rate-limit statistics as CSV for a superuser.")
+    @SecurityRequirement(name = "DataverseApiKey")
     public Response rateLimitStats(@Context ContainerRequestContext crc,
+                                   @Parameter(description = "Limit statistics to entries within this many minutes.")
                                    @QueryParam("deltaMinutesFilter") Long deltaMinutesFilter) {
         try {
             AuthenticatedUser user = getRequestAuthenticatedUserOrDie(crc);
diff --git a/src/main/java/edu/harvard/iq/dataverse/api/ApiConfiguration.java b/src/main/java/edu/harvard/iq/dataverse/api/ApiConfiguration.java
index f7c4e7e105f..3fc89b122f1 100644
--- a/src/main/java/edu/harvard/iq/dataverse/api/ApiConfiguration.java
+++ b/src/main/java/edu/harvard/iq/dataverse/api/ApiConfiguration.java
@@ -2,10 +2,20 @@
 
 import jakarta.ws.rs.ApplicationPath;
 
+import org.eclipse.microprofile.openapi.annotations.enums.SecuritySchemeIn;
+import org.eclipse.microprofile.openapi.annotations.enums.SecuritySchemeType;
+import org.eclipse.microprofile.openapi.annotations.security.SecurityScheme;
 import org.glassfish.jersey.media.multipart.MultiPartFeature;
 import org.glassfish.jersey.server.ResourceConfig;
 
 @ApplicationPath("api/v1")
+@SecurityScheme(
+        securitySchemeName = "DataverseApiKey",
+        type = SecuritySchemeType.APIKEY,
+        in = SecuritySchemeIn.HEADER,
+        apiKeyName = "X-Dataverse-key",
+        description = "Dataverse API token."
+)
 public class ApiConfiguration extends ResourceConfig {
    
    public ApiConfiguration() {
diff --git a/src/main/java/edu/harvard/iq/dataverse/api/BatchImport.java b/src/main/java/edu/harvard/iq/dataverse/api/BatchImport.java
index a2d06bff93e..1a5cd418c6a 100644
--- a/src/main/java/edu/harvard/iq/dataverse/api/BatchImport.java
+++ b/src/main/java/edu/harvard/iq/dataverse/api/BatchImport.java
@@ -25,9 +25,16 @@
 import jakarta.ws.rs.container.ContainerRequestContext;
 import jakarta.ws.rs.core.Context;
 import jakarta.ws.rs.core.Response;
+import org.eclipse.microprofile.openapi.annotations.Operation;
+import org.eclipse.microprofile.openapi.annotations.parameters.Parameter;
+import org.eclipse.microprofile.openapi.annotations.parameters.RequestBody;
+import org.eclipse.microprofile.openapi.annotations.security.SecurityRequirement;
+import org.eclipse.microprofile.openapi.annotations.tags.Tag;
 
 @Stateless
 @Path("batch")
+@SecurityRequirement(name = "DataverseApiKey")
+@Tag(name = "Admin", description = "Administrative Dataverse operations.")
 public class BatchImport extends AbstractApiBean {
 
     @EJB
@@ -48,7 +55,17 @@ public class BatchImport extends AbstractApiBean {
     @GET
     @AuthRequired
     @Path("harvest")
-    public Response harvest(@Context ContainerRequestContext crc, @QueryParam("path") String fileDir, @QueryParam("dv") String parentIdtf, @QueryParam("createDV") Boolean createDV, @QueryParam("key") String apiKey) throws IOException {
+    @Operation(summary = "Starts a harvest batch import",
+            description = "Starts a background harvest import from a server-side file or directory into the specified dataverse.")
+    public Response harvest(@Context ContainerRequestContext crc,
+            @Parameter(description = "Server-side file or directory path to import.", required = true)
+            @QueryParam("path") String fileDir,
+            @Parameter(description = "Target dataverse id or alias; defaults to root when omitted.")
+            @QueryParam("dv") String parentIdtf,
+            @Parameter(description = "Create the target dataverse when it does not exist.")
+            @QueryParam("createDV") Boolean createDV,
+            @Parameter(hidden = true)
+            @QueryParam("key") String apiKey) throws IOException {
         try {
             return startBatchJob(getRequestAuthenticatedUserOrDie(crc), fileDir, parentIdtf, apiKey, ImportType.HARVEST, createDV);
         } catch (WrappedResponse wr) {
@@ -67,7 +84,15 @@ public Response harvest(@Context ContainerRequestContext crc, @QueryParam("path"
     @POST
     @AuthRequired
     @Path("import")
-    public Response postImport(@Context ContainerRequestContext crc, String body, @QueryParam("dv") String parentIdtf, @QueryParam("key") String apiKey) {
+    @Operation(summary = "Imports a dataset from DDI XML",
+            description = "Imports a new dataset into the specified dataverse from DDI XML supplied in the request body.")
+    public Response postImport(@Context ContainerRequestContext crc,
+            @RequestBody(description = "DDI XML dataset metadata to import as a new dataset.")
+            String body,
+            @Parameter(description = "Target dataverse id or alias; defaults to root when omitted.")
+            @QueryParam("dv") String parentIdtf,
+            @Parameter(hidden = true)
+            @QueryParam("key") String apiKey) {
 
         DataverseRequest dataverseRequest;
         try {
@@ -105,7 +130,17 @@ public Response postImport(@Context ContainerRequestContext crc, String body, @Q
     @GET
     @AuthRequired
     @Path("import")
-    public Response getImport(@Context ContainerRequestContext crc, @QueryParam("path") String fileDir, @QueryParam("dv") String parentIdtf, @QueryParam("createDV") Boolean createDV, @QueryParam("key") String apiKey) {
+    @Operation(summary = "Starts a dataset batch import",
+            description = "Starts a background import of one or more datasets from a server-side file or directory into the specified dataverse.")
+    public Response getImport(@Context ContainerRequestContext crc,
+            @Parameter(description = "Server-side file or directory path to import.", required = true)
+            @QueryParam("path") String fileDir,
+            @Parameter(description = "Target dataverse id or alias; defaults to root when omitted.")
+            @QueryParam("dv") String parentIdtf,
+            @Parameter(description = "Create the target dataverse when it does not exist.")
+            @QueryParam("createDV") Boolean createDV,
+            @Parameter(hidden = true)
+            @QueryParam("key") String apiKey) {
         try {
             return startBatchJob(getRequestAuthenticatedUserOrDie(crc), fileDir, parentIdtf, apiKey, ImportType.NEW, createDV);
         } catch (WrappedResponse wr) {
diff --git a/src/main/java/edu/harvard/iq/dataverse/api/BuiltinUsers.java b/src/main/java/edu/harvard/iq/dataverse/api/BuiltinUsers.java
index 79d5682d4f3..de1e0e1fdc0 100644
--- a/src/main/java/edu/harvard/iq/dataverse/api/BuiltinUsers.java
+++ b/src/main/java/edu/harvard/iq/dataverse/api/BuiltinUsers.java
@@ -29,6 +29,10 @@
 import jakarta.ws.rs.core.Response.Status;
 import java.util.Date;
 import static edu.harvard.iq.dataverse.util.json.JsonPrinter.json;
+import org.eclipse.microprofile.openapi.annotations.Operation;
+import org.eclipse.microprofile.openapi.annotations.parameters.Parameter;
+import org.eclipse.microprofile.openapi.annotations.parameters.RequestBody;
+import org.eclipse.microprofile.openapi.annotations.tags.Tag;
 
 /**
  * REST API bean for managing {@link BuiltinUser}s.
@@ -36,6 +40,7 @@
  * @author michael
  */
 @Path("builtin-users")
+@Tag(name = "Users", description = "User account and authenticated user operations.")
 public class BuiltinUsers extends AbstractApiBean {
 
     private static final Logger logger = Logger.getLogger(BuiltinUsers.class.getName());
@@ -45,7 +50,13 @@ public class BuiltinUsers extends AbstractApiBean {
 
     @GET
     @Path("{username}/api-token")
-    public Response getApiToken( @PathParam("username") String username, @QueryParam("password") String password ) {
+    @Operation(summary = "Returns a builtin user's API token",
+            description = "Returns the API token for a builtin user when token lookup is enabled and the supplied password is valid.")
+    public Response getApiToken(
+            @Parameter(description = "Builtin username whose API token is requested.", required = true)
+            @PathParam("username") String username,
+            @Parameter(description = "Builtin account password used to verify token lookup.")
+            @QueryParam("password") String password) {
         boolean disabled = true;
         boolean lookupAllowed = settingsSvc.isTrueForKey(SettingsServiceBean.Key.AllowApiTokenLookupViaApi, false);
         if (lookupAllowed) {
@@ -80,7 +91,17 @@ public Response getApiToken( @PathParam("username") String username, @QueryParam
     //and use the values to create BuiltinUser/AuthenticatedUser.
     //--MAD 4.9.3
     @POST
-    public Response save(BuiltinUser user, @QueryParam("password") String password, @QueryParam("key") String key, @QueryParam("sendEmailNotification") Boolean sendEmailNotification) {   
+    @Operation(summary = "Creates a builtin user",
+            description = "Creates a builtin user, matching authenticated user, and API token when the builtin-users management key is valid.")
+    public Response save(
+            @RequestBody(description = "Builtin user account data used to create the builtin and authenticated user records.")
+            BuiltinUser user,
+            @Parameter(description = "Password assigned to the builtin user.")
+            @QueryParam("password") String password,
+            @Parameter(description = "Builtin-users management key required to create the account.")
+            @QueryParam("key") String key,
+            @Parameter(description = "Send a create-account email notification to the new user.")
+            @QueryParam("sendEmailNotification") Boolean sendEmailNotification) {
         if( sendEmailNotification == null )
             sendEmailNotification = true;
         
@@ -100,7 +121,15 @@ public Response save(BuiltinUser user, @QueryParam("password") String password,
      */
     @POST
     @Path("{password}/{key}")
-    public Response create(BuiltinUser user, @PathParam("password") String password, @PathParam("key") String key) {
+    @Operation(summary = "Creates a builtin user with path credentials",
+            description = "Creates a builtin user, matching authenticated user, and API token using password and management key path values.")
+    public Response create(
+            @RequestBody(description = "Builtin user account data used to create the builtin and authenticated user records.")
+            BuiltinUser user,
+            @Parameter(description = "Password assigned to the builtin user.", required = true)
+            @PathParam("password") String password,
+            @Parameter(description = "Builtin-users management key required to create the account.", required = true)
+            @PathParam("key") String key) {
         return internalSave(user, password, key);
     }
     
@@ -117,7 +146,17 @@ public Response create(BuiltinUser user, @PathParam("password") String password,
      */
     @POST
     @Path("{password}/{key}/{sendEmailNotification}")
-    public Response createWithNotification(BuiltinUser user, @PathParam("password") String password, @PathParam("key") String key, @PathParam("sendEmailNotification") Boolean sendEmailNotification) {
+    @Operation(summary = "Creates a builtin user with notification control",
+            description = "Creates a builtin user, matching authenticated user, and API token while controlling whether a create-account notification is sent.")
+    public Response createWithNotification(
+            @RequestBody(description = "Builtin user account data used to create the builtin and authenticated user records.")
+            BuiltinUser user,
+            @Parameter(description = "Password assigned to the builtin user.", required = true)
+            @PathParam("password") String password,
+            @Parameter(description = "Builtin-users management key required to create the account.", required = true)
+            @PathParam("key") String key,
+            @Parameter(description = "Send a create-account email notification to the new user.", required = true)
+            @PathParam("sendEmailNotification") Boolean sendEmailNotification) {
         return internalSave(user, password, key, sendEmailNotification);
     }
     
diff --git a/src/main/java/edu/harvard/iq/dataverse/api/DataTagsAPI.java b/src/main/java/edu/harvard/iq/dataverse/api/DataTagsAPI.java
index d7c8bd827d1..50d69924feb 100644
--- a/src/main/java/edu/harvard/iq/dataverse/api/DataTagsAPI.java
+++ b/src/main/java/edu/harvard/iq/dataverse/api/DataTagsAPI.java
@@ -17,6 +17,10 @@
 import jakarta.ws.rs.client.WebTarget;
 import jakarta.ws.rs.core.MediaType;
 import jakarta.ws.rs.core.Response;
+import org.eclipse.microprofile.openapi.annotations.Operation;
+import org.eclipse.microprofile.openapi.annotations.parameters.Parameter;
+import org.eclipse.microprofile.openapi.annotations.parameters.RequestBody;
+import org.eclipse.microprofile.openapi.annotations.tags.Tag;
 
 /**
  *
@@ -24,6 +28,7 @@
  */
 @Stateless
 @Path("datatags")
+@Tag(name = "Datasets", description = "Dataset metadata, versions, files, and publishing operations.")
 public class DataTagsAPI extends AbstractApiBean { 
     
     private static final String TAGGING_SERVER_ENDPOINT = "http://datatags.org/api/1/interviewLink";
@@ -76,7 +81,13 @@ public String getCallbackURL() {
     
     @POST
     @Path("receiveTags/{uniqueCacheId}")
-    public Response receiveTags(JsonObject tags, @PathParam("uniqueCacheId") String uniqueCacheId) {
+    @Operation(summary = "Receives DataTags results",
+            description = "Stores returned DataTags JSON in the callback cache and returns the Dataverse redirect URL.")
+    public Response receiveTags(
+            @RequestBody(description = "DataTags result JSON returned by the external tagging interview.")
+            JsonObject tags,
+            @Parameter(description = "Callback cache identifier associated with the DataTags interview.", required = true)
+            @PathParam("uniqueCacheId") String uniqueCacheId) {
         
         // store json tags in the DataTagsContainer holding the dataset name
         container.setTag(tags);
@@ -86,4 +97,4 @@ public Response receiveTags(JsonObject tags, @PathParam("uniqueCacheId") String
         return ok( USER_REDIRECT_URL );
     }
     
-}
\ No newline at end of file
+}
diff --git a/src/main/java/edu/harvard/iq/dataverse/api/DatasetFieldServiceApi.java b/src/main/java/edu/harvard/iq/dataverse/api/DatasetFieldServiceApi.java
index f29387aeb56..20dc70d4833 100644
--- a/src/main/java/edu/harvard/iq/dataverse/api/DatasetFieldServiceApi.java
+++ b/src/main/java/edu/harvard/iq/dataverse/api/DatasetFieldServiceApi.java
@@ -53,8 +53,13 @@
 import java.util.Enumeration;
 import java.util.zip.ZipEntry;
 import java.util.zip.ZipFile;
+import org.eclipse.microprofile.openapi.annotations.Operation;
+import org.eclipse.microprofile.openapi.annotations.parameters.Parameter;
+import org.eclipse.microprofile.openapi.annotations.parameters.RequestBody;
+import org.eclipse.microprofile.openapi.annotations.tags.Tag;
 
 @Path("admin/datasetfield")
+@Tag(name = "Dataset Fields", description = "Dataset field type, controlled vocabulary, and metadata block loading operations.")
 public class DatasetFieldServiceApi extends AbstractApiBean {
 
     @EJB
@@ -72,6 +77,8 @@ public class DatasetFieldServiceApi extends AbstractApiBean {
     private static final Logger logger = Logger.getLogger(DatasetFieldServiceApi.class.getName());
     
     @GET
+    @Operation(summary = "Lists dataset field groupings",
+            description = "Returns dataset field type names grouped by parent relationship, multiplicity, and required status.")
     public Response getAll() {
         try {
             List<String> listOfIsHasParentsTrue = new ArrayList<>();
@@ -118,7 +125,11 @@ public Response getAll() {
 
     @GET
     @Path("{name}")
-    public Response getByName(@PathParam("name") String name) {
+    @Operation(summary = "Returns a dataset field type",
+            description = "Returns a dataset field type with metadata block, Solr field names, parent relationship, multiplicity, required state, URI, and controlled vocabulary values.")
+    public Response getByName(
+            @Parameter(description = "Dataset field type name to return.", required = true)
+            @PathParam("name") String name) {
         try {
             DatasetFieldType dsf = datasetFieldService.findByName(name);
             Long id = dsf.getId();
@@ -190,6 +201,8 @@ public Response getByName(@PathParam("name") String name) {
      */
     @GET
     @Path("controlledVocabulary/subject")
+    @Operation(summary = "Lists subject vocabulary values",
+            description = "Returns the configured controlled vocabulary display values for the subject dataset field.")
     public Response showControlledVocabularyForSubject() {
         DatasetFieldType subjectDatasetField = datasetFieldService.findByName(DatasetFieldConstant.subject);
         JsonArrayBuilder possibleSubjects = Json.createArrayBuilder();
@@ -206,6 +219,8 @@ public Response showControlledVocabularyForSubject() {
     // TODO consider replacing with a @Startup method on the datasetFieldServiceBean
     @GET
     @Path("loadNAControlledVocabularyValue")
+    @Operation(summary = "Creates the N/A controlled vocabulary value",
+            description = "Creates the global N/A controlled vocabulary value when it is missing and reports whether it was created or already existed.")
     public Response loadNAControlledVocabularyValue() {
         // the find will throw a NoResultException if no values are in db
 //            datasetFieldService.findNAControlledVocabularyValue();
@@ -230,7 +245,11 @@ public enum HeaderType {
     @POST
     @Consumes("text/tab-separated-values")
     @Path("load")
-    public Response loadDatasetFields(File file) {
+    @Operation(summary = "Loads dataset field definitions",
+            description = "Reads tab-separated metadata block, dataset field, and controlled vocabulary definitions from the uploaded file path and creates or updates those definitions.")
+    public Response loadDatasetFields(
+            @RequestBody(description = "Tab-separated definitions for metadata blocks, dataset fields, and controlled vocabulary values.")
+            File file) {
         ActionLogRecord alr = new ActionLogRecord(ActionLogRecord.ActionType.Admin, "loadDatasetFields");
         alr.setInfo( file.getName() );
         BufferedReader br = null;
@@ -489,7 +508,11 @@ private String parseControlledVocabulary(String[] values) {
     @POST
     @Consumes("application/zip")
     @Path("loadpropertyfiles")
-    public Response loadLanguagePropertyFile(File inputFile) {
+    @Operation(summary = "Loads language property files",
+            description = "Extracts uploaded language property files into the configured Dataverse language directory while rejecting ZIP entries outside that directory.")
+    public Response loadLanguagePropertyFile(
+            @RequestBody(description = "ZIP archive containing language property files to extract.")
+            File inputFile) {
         try (ZipFile file = new ZipFile(inputFile)) {
             //Get file entries
             Enumeration<? extends ZipEntry> entries = file.entries();
@@ -551,7 +574,13 @@ public static String getDataverseLangDirectory() {
      */
     @POST
     @Path("/setDisplayOnCreate")
-    public Response setDisplayOnCreate(@QueryParam("datasetFieldType") String datasetFieldTypeIn, @QueryParam("setDisplayOnCreate") Boolean setDisplayOnCreateIn) {
+    @Operation(summary = "Sets dataset field create-page display",
+            description = "Updates whether the specified dataset field type is displayed on the dataset creation page.")
+    public Response setDisplayOnCreate(
+            @Parameter(description = "Dataset field type name to update.", required = true)
+            @QueryParam("datasetFieldType") String datasetFieldTypeIn,
+            @Parameter(description = "New display-on-create setting for the dataset field type.", required = true)
+            @QueryParam("setDisplayOnCreate") Boolean setDisplayOnCreateIn) {
         DatasetFieldType dft = datasetFieldService.findByName(datasetFieldTypeIn);
         if (dft == null) {
             return error(Status.NOT_FOUND, "Cound not find a DatasetFieldType by looking up " + datasetFieldTypeIn);
diff --git a/src/main/java/edu/harvard/iq/dataverse/api/DatasetFields.java b/src/main/java/edu/harvard/iq/dataverse/api/DatasetFields.java
index 2ec35c896d9..8aad30f34f3 100644
--- a/src/main/java/edu/harvard/iq/dataverse/api/DatasetFields.java
+++ b/src/main/java/edu/harvard/iq/dataverse/api/DatasetFields.java
@@ -7,6 +7,8 @@
 import jakarta.ws.rs.core.Response;
 
 import java.util.List;
+import org.eclipse.microprofile.openapi.annotations.Operation;
+import org.eclipse.microprofile.openapi.annotations.tags.Tag;
 
 import static edu.harvard.iq.dataverse.util.json.JsonPrinter.jsonDatasetFieldTypes;
 
@@ -15,6 +17,7 @@
  */
 @Path("datasetfields")
 @Produces("application/json")
+@Tag(name = "Dataset Fields", description = "Dataset field type, controlled vocabulary, and metadata block loading operations.")
 public class DatasetFields extends AbstractApiBean {
 
     @EJB
@@ -22,6 +25,8 @@ public class DatasetFields extends AbstractApiBean {
 
     @GET
     @Path("facetables")
+    @Operation(summary = "Lists facetable dataset fields",
+            description = "Lists all facetable dataset fields defined in the installation.")
     public Response listAllFacetableDatasetFields() {
         List<DatasetFieldType> datasetFieldTypes = datasetFieldService.findAllFacetableFieldTypes();
         return ok(jsonDatasetFieldTypes(datasetFieldTypes));
diff --git a/src/main/java/edu/harvard/iq/dataverse/api/Datasets.java b/src/main/java/edu/harvard/iq/dataverse/api/Datasets.java
index 136b6dbb69b..85abeb11d2a 100644
--- a/src/main/java/edu/harvard/iq/dataverse/api/Datasets.java
+++ b/src/main/java/edu/harvard/iq/dataverse/api/Datasets.java
@@ -79,8 +79,10 @@
 import org.apache.logging.log4j.util.Strings;
 import org.eclipse.microprofile.openapi.annotations.Operation;
 import org.eclipse.microprofile.openapi.annotations.media.Content;
+import org.eclipse.microprofile.openapi.annotations.parameters.Parameter;
 import org.eclipse.microprofile.openapi.annotations.parameters.RequestBody;
 import org.eclipse.microprofile.openapi.annotations.responses.APIResponse;
+import org.eclipse.microprofile.openapi.annotations.security.SecurityRequirement;
 import org.eclipse.microprofile.openapi.annotations.tags.Tag;
 import org.glassfish.jersey.media.multipart.FormDataBodyPart;
 import org.glassfish.jersey.media.multipart.FormDataContentDisposition;
@@ -117,6 +119,7 @@
 import static jakarta.ws.rs.core.Response.Status.FORBIDDEN;
 
 @Path("datasets")
+@Tag(name = "Datasets", description = "Manage datasets, versions, files, metadata, publication, and dataset administration.")
 public class Datasets extends AbstractApiBean {
 
     private static final Logger logger = Logger.getLogger(Datasets.class.getCanonicalName());
@@ -219,7 +222,15 @@ public interface DsVersionHandler<T> {
     @GET
     @AuthRequired
     @Path("{id}")
-    public Response getDataset(@Context ContainerRequestContext crc, @PathParam("id") String id, @Context UriInfo uriInfo, @Context HttpHeaders headers, @Context HttpServletResponse response,  @QueryParam("returnOwners") boolean returnOwners) {
+    @Operation(summary = "Read dataset details",
+            description = "Returns dataset metadata and the latest accessible version, and records metrics for released dataset access.")
+    @SecurityRequirement(name = "DataverseApiKey")
+    public Response getDataset(@Context ContainerRequestContext crc,
+            @Parameter(description = "Dataset id or persistent identifier.", required = true)
+            @PathParam("id") String id,
+            @Context UriInfo uriInfo, @Context HttpHeaders headers, @Context HttpServletResponse response,
+            @Parameter(description = "Whether to include owner information in the response.")
+            @QueryParam("returnOwners") boolean returnOwners) {
         return response( req -> {
             final Dataset retrieved = execCommand(new GetDatasetCommand(req, findDatasetOrDie(id, true)));
             final DatasetVersion latest = execCommand(new GetLatestAccessibleDatasetVersionCommand(req, retrieved));
@@ -237,6 +248,9 @@ public Response getDataset(@Context ContainerRequestContext crc, @PathParam("id"
     @AuthRequired
     @Path("/export")
     @Produces({"application/xml", "application/json", "application/html", "application/ld+json", "*/*" })
+    @Operation(summary = "Export dataset metadata",
+            description = "Exports dataset metadata by persistent id using the requested version and exporter.")
+    @SecurityRequirement(name = "DataverseApiKey")
     public Response exportDataset(@Context ContainerRequestContext crc, @QueryParam("persistentId") String persistentId,
             @QueryParam("version") String versionId, @QueryParam("exporter") String exporter,
             @Context UriInfo uriInfo, @Context HttpHeaders headers, @Context HttpServletResponse response) {
@@ -720,7 +734,14 @@ public Response getVersionMetadataBlock(@Context ContainerRequestContext crc,
     @GET
     @AuthRequired
     @Path("{id}/versions/{versionId}/linkset")
-    public Response getLinkset(@Context ContainerRequestContext crc, @PathParam("id") String datasetId, @PathParam("versionId") String versionId,
+    @Operation(summary = "Build a dataset version linkset",
+            description = "Generates signposting linkset JSON for a released dataset version.")
+    @SecurityRequirement(name = "DataverseApiKey")
+    public Response getLinkset(@Context ContainerRequestContext crc,
+           @Parameter(description = "Dataset id or persistent identifier.", required = true)
+           @PathParam("id") String datasetId,
+           @Parameter(description = "Dataset version id or version label.", required = true)
+           @PathParam("versionId") String versionId,
            @Context UriInfo uriInfo, @Context HttpHeaders headers) {
         if (DS_VERSION_DRAFT.equals(versionId)) {
             return badRequest("Signposting is not supported on the " + DS_VERSION_DRAFT + " version");
@@ -745,7 +766,12 @@ public Response getLinkset(@Context ContainerRequestContext crc, @PathParam("id"
     @POST
     @AuthRequired
     @Path("{id}/modifyRegistration")
-    public Response updateDatasetTargetURL(@Context ContainerRequestContext crc, @PathParam("id") String id ) {
+    @Operation(summary = "Refresh a dataset registration target URL",
+            description = "Updates the target URL stored with the persistent identifier provider for one dataset.")
+    @SecurityRequirement(name = "DataverseApiKey")
+    public Response updateDatasetTargetURL(@Context ContainerRequestContext crc,
+            @Parameter(description = "Dataset id or persistent identifier.", required = true)
+            @PathParam("id") String id ) {
         return response( req -> {
             execCommand(new UpdateDatasetTargetURLCommand(findDatasetOrDie(id), req));
             return ok("Dataset " + id + " target url updated");
@@ -755,6 +781,9 @@ public Response updateDatasetTargetURL(@Context ContainerRequestContext crc, @Pa
     @POST
     @AuthRequired
     @Path("/modifyRegistrationAll")
+    @Operation(summary = "Refresh registration target URLs for all datasets",
+            description = "Updates persistent identifier target URLs for every dataset.")
+    @SecurityRequirement(name = "DataverseApiKey")
     public Response updateDatasetTargetURLAll(@Context ContainerRequestContext crc) {
         return response( req -> {
             datasetService.findAll().forEach( ds -> {
@@ -771,7 +800,12 @@ public Response updateDatasetTargetURLAll(@Context ContainerRequestContext crc)
     @POST
     @AuthRequired
     @Path("{id}/modifyRegistrationMetadata")
-    public Response updateDatasetPIDMetadata(@Context ContainerRequestContext crc, @PathParam("id") String id) {
+    @Operation(summary = "Refresh persistent identifier metadata for a dataset",
+            description = "Updates provider metadata for the persistent identifier associated with one released dataset.")
+    @SecurityRequirement(name = "DataverseApiKey")
+    public Response updateDatasetPIDMetadata(@Context ContainerRequestContext crc,
+            @Parameter(description = "Dataset id or persistent identifier.", required = true)
+            @PathParam("id") String id) {
 
         try {
             Dataset dataset = findDatasetOrDie(id);
@@ -793,6 +827,9 @@ public Response updateDatasetPIDMetadata(@Context ContainerRequestContext crc, @
     @POST
     @AuthRequired
     @Path("/modifyRegistrationPIDMetadataAll")
+    @Operation(summary = "Refresh persistent identifier metadata for all datasets",
+            description = "Updates provider metadata for persistent identifiers associated with all released datasets.")
+    @SecurityRequirement(name = "DataverseApiKey")
     public Response updateDatasetPIDMetadataAll(@Context ContainerRequestContext crc) {
         return response( req -> {
             datasetService.findAll().forEach( ds -> {
@@ -817,7 +854,16 @@ public Response updateDatasetPIDMetadataAll(@Context ContainerRequestContext crc
     @AuthRequired
     @Path("{id}/versions/{versionId}")
     @Consumes(MediaType.APPLICATION_JSON)
-    public Response updateDraftVersion(@Context ContainerRequestContext crc, String jsonBody, @PathParam("id") String id, @PathParam("versionId") String versionId) {
+    @Operation(summary = "Replace draft version metadata",
+            description = "Updates the draft dataset version from the supplied JSON dataset-version payload.")
+    @SecurityRequirement(name = "DataverseApiKey")
+    public Response updateDraftVersion(@Context ContainerRequestContext crc,
+            @RequestBody(description = "Dataset version JSON used to replace draft metadata.")
+            String jsonBody,
+            @Parameter(description = "Dataset id or persistent identifier.", required = true)
+            @PathParam("id") String id,
+            @Parameter(description = "Dataset version id; only :draft is accepted.", required = true)
+            @PathParam("versionId") String versionId) {
         if (!DS_VERSION_DRAFT.equals(versionId)) {
             return error( Response.Status.BAD_REQUEST, "Only the " + DS_VERSION_DRAFT + " version can be updated");
         }
@@ -879,7 +925,15 @@ public Response updateDraftVersion(@Context ContainerRequestContext crc, String
     @AuthRequired
     @Path("{id}/versions/{versionId}/metadata")
     @Produces("application/ld+json, application/json-ld")
-    public Response getVersionJsonLDMetadata(@Context ContainerRequestContext crc, @PathParam("id") String id, @PathParam("versionId") String versionId, @Context UriInfo uriInfo, @Context HttpHeaders headers) {
+    @Operation(summary = "Read JSON-LD metadata for a dataset version",
+            description = "Exports JSON-LD metadata for the requested dataset version.")
+    @SecurityRequirement(name = "DataverseApiKey")
+    public Response getVersionJsonLDMetadata(@Context ContainerRequestContext crc,
+            @Parameter(description = "Dataset id or persistent identifier.", required = true)
+            @PathParam("id") String id,
+            @Parameter(description = "Dataset version id or version label.", required = true)
+            @PathParam("versionId") String versionId,
+            @Context UriInfo uriInfo, @Context HttpHeaders headers) {
         try {
             DataverseRequest req = createDataverseRequest(getRequestUser(crc));
             DatasetVersion dsv = getDatasetVersionOrDie(req, versionId, findDatasetOrDie(id), uriInfo, headers);
@@ -901,7 +955,13 @@ public Response getVersionJsonLDMetadata(@Context ContainerRequestContext crc, @
     @AuthRequired
     @Path("{id}/metadata")
     @Produces("application/ld+json, application/json-ld")
-    public Response getJsonLDMetadata(@Context ContainerRequestContext crc, @PathParam("id") String id, @Context UriInfo uriInfo, @Context HttpHeaders headers) {
+    @Operation(summary = "Read latest JSON-LD metadata",
+            description = "Exports JSON-LD metadata for the latest accessible dataset version.")
+    @SecurityRequirement(name = "DataverseApiKey")
+    public Response getJsonLDMetadata(@Context ContainerRequestContext crc,
+            @Parameter(description = "Dataset id or persistent identifier.", required = true)
+            @PathParam("id") String id,
+            @Context UriInfo uriInfo, @Context HttpHeaders headers) {
         return getVersionJsonLDMetadata(crc, id, DS_VERSION_LATEST, uriInfo, headers);
     }
 
@@ -909,7 +969,16 @@ public Response getJsonLDMetadata(@Context ContainerRequestContext crc, @PathPar
     @AuthRequired
     @Path("{id}/metadata")
     @Consumes("application/ld+json, application/json-ld")
-    public Response updateVersionMetadata(@Context ContainerRequestContext crc, String jsonLDBody, @PathParam("id") String id, @DefaultValue("false") @QueryParam("replace") boolean replaceTerms) {
+    @Operation(summary = "Apply JSON-LD metadata to a dataset",
+            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.")
+            String jsonLDBody,
+            @Parameter(description = "Dataset id or persistent identifier.", required = true)
+            @PathParam("id") String id,
+            @Parameter(description = "When true, replace existing terms instead of merging supplied values.")
+            @DefaultValue("false") @QueryParam("replace") boolean replaceTerms) {
 
         try {
             Dataset ds = findDatasetOrDie(id);
@@ -943,7 +1012,14 @@ public Response updateVersionMetadata(@Context ContainerRequestContext crc, Stri
     @AuthRequired
     @Path("{id}/metadata/delete")
     @Consumes("application/ld+json, application/json-ld")
-    public Response deleteMetadata(@Context ContainerRequestContext crc, String jsonLDBody, @PathParam("id") String id) {
+    @Operation(summary = "Remove JSON-LD metadata from a dataset",
+            description = "Deletes dataset metadata values described by the supplied JSON-LD payload.")
+    @SecurityRequirement(name = "DataverseApiKey")
+    public Response deleteMetadata(@Context ContainerRequestContext crc,
+            @RequestBody(description = "JSON-LD metadata values to remove from the dataset draft.")
+            String jsonLDBody,
+            @Parameter(description = "Dataset id or persistent identifier.", required = true)
+            @PathParam("id") String id) {
         try {
             Dataset ds = findDatasetOrDie(id);
             DataverseRequest req = createDataverseRequest(getRequestUser(crc));
@@ -973,7 +1049,14 @@ public Response deleteMetadata(@Context ContainerRequestContext crc, String json
     @PUT
     @AuthRequired
     @Path("{id}/deleteMetadata")
-    public Response deleteVersionMetadata(@Context ContainerRequestContext crc, String jsonBody, @PathParam("id") String id) throws WrappedResponse {
+    @Operation(summary = "Remove metadata fields from a dataset draft",
+            description = "Deletes metadata fields or field values from the dataset draft using the supplied JSON payload.")
+    @SecurityRequirement(name = "DataverseApiKey")
+    public Response deleteVersionMetadata(@Context ContainerRequestContext crc,
+            @RequestBody(description = "JSON metadata fields or values to remove from the dataset draft.")
+            String jsonBody,
+            @Parameter(description = "Dataset id or persistent identifier.", required = true)
+            @PathParam("id") String id) throws WrappedResponse {
 
         DataverseRequest req = createDataverseRequest(getRequestUser(crc));
 
@@ -1127,8 +1210,17 @@ private String getCompoundDisplayValue (DatasetFieldCompoundValue dscv){
     @PUT
     @AuthRequired
     @Path("{id}/editMetadata")
-    public Response editVersionMetadata(@Context ContainerRequestContext crc, String jsonBody, @PathParam("id") String id,
+    @Operation(summary = "Edit dataset draft metadata",
+            description = "Adds, merges, or replaces dataset metadata fields on the draft version.")
+    @SecurityRequirement(name = "DataverseApiKey")
+    public Response editVersionMetadata(@Context ContainerRequestContext crc,
+                                        @RequestBody(description = "JSON metadata fields to add, merge, or replace.")
+                                        String jsonBody,
+                                        @Parameter(description = "Dataset id or persistent identifier.", required = true)
+                                        @PathParam("id") String id,
+                                        @Parameter(description = "When true, replace matching field values instead of merging.")
                                         @QueryParam("replace") boolean replaceData,
+                                        @Parameter(description = "Source last-update timestamp used by external integrations.")
                                         @QueryParam("sourceLastUpdateTime") String sourceLastUpdateTime) {
         try {
             Dataset dataset = findDatasetOrDie(id);
@@ -1162,7 +1254,15 @@ public Response editVersionMetadata(@Context ContainerRequestContext crc, String
     @PUT
     @AuthRequired
     @Path("{id}/access")
-    public Response editVersionTermsOfAccess(@Context ContainerRequestContext crc, String jsonBody, @PathParam("id") String id,
+    @Operation(summary = "Edit dataset terms of access",
+            description = "Updates terms of use and access settings on the dataset draft.")
+    @SecurityRequirement(name = "DataverseApiKey")
+    public Response editVersionTermsOfAccess(@Context ContainerRequestContext crc,
+                                        @RequestBody(description = "JSON terms-of-access payload for the dataset draft.")
+                                        String jsonBody,
+                                        @Parameter(description = "Dataset id or persistent identifier.", required = true)
+                                        @PathParam("id") String id,
+                                        @Parameter(description = "Source last-update timestamp used by external integrations.")
                                         @QueryParam("sourceLastUpdateTime") String sourceLastUpdateTime) {
         try {
 
@@ -1202,7 +1302,14 @@ public Response editVersionTermsOfAccess(@Context ContainerRequestContext crc, S
     @AuthRequired
     @Path("{id}/actions/:publish")
     @Deprecated
-    public Response publishDataseUsingGetDeprecated(@Context ContainerRequestContext crc, @PathParam("id") String id, @QueryParam("type") String type ) {
+    @Operation(summary = "Publish a dataset through the deprecated GET route",
+            description = "Publishes a dataset version using the legacy GET endpoint retained for compatibility.")
+    @SecurityRequirement(name = "DataverseApiKey")
+    public Response publishDataseUsingGetDeprecated(@Context ContainerRequestContext crc,
+            @Parameter(description = "Dataset id or persistent identifier.", required = true)
+            @PathParam("id") String id,
+            @Parameter(description = "Publication type: major, minor, or updatecurrent.", required = true)
+            @QueryParam("type") String type ) {
         logger.info("publishDataseUsingGetDeprecated called on id " + id + ". Encourage use of POST rather than GET, which is deprecated.");
         return publishDataset(crc, id, type, false);
     }
@@ -1210,7 +1317,14 @@ public Response publishDataseUsingGetDeprecated(@Context ContainerRequestContext
     @POST
     @AuthRequired
     @Path("{id}/actions/:publish")
-    public Response publishDataset(@Context ContainerRequestContext crc, @PathParam("id") String id, @QueryParam("type") String type, @QueryParam("assureIsIndexed") boolean mustBeIndexed) {
+    @SecurityRequirement(name = "DataverseApiKey")
+    public Response publishDataset(@Context ContainerRequestContext crc,
+            @Parameter(description = "Dataset id or persistent identifier.", required = true)
+            @PathParam("id") String id,
+            @Parameter(description = "Publication type: major, minor, or updatecurrent.", required = true)
+            @QueryParam("type") String type,
+            @Parameter(description = "When true, require the dataset to be indexed before publication completes.")
+            @QueryParam("assureIsIndexed") boolean mustBeIndexed) {
         try {
             if (type == null) {
                 return error(Response.Status.BAD_REQUEST, "Missing 'type' parameter (either 'major','minor', or 'updatecurrent').");
@@ -5754,6 +5868,9 @@ public Response resetPidGenerator(@Context ContainerRequestContext crc, @PathPar
 
     @GET
     @Path("datasetTypes")
+    @Operation(summary = "Present configured dataset types",
+            description = "Provides all dataset types configured for datasets.",
+            operationId = "Datasets_listDatasetTypes")
     public Response getDatasetTypes(@HeaderParam(ACCEPT_LANGUAGE) String acceptLanguage) {
         Locale locale = I18nUtil.parseAcceptLanguageHeader(acceptLanguage);
         JsonArrayBuilder jab = Json.createArrayBuilder();
@@ -5765,7 +5882,12 @@ public Response getDatasetTypes(@HeaderParam(ACCEPT_LANGUAGE) String acceptLangu
 
     @GET
     @Path("datasetTypes/{idOrName}")
-    public Response getDatasetTypes(@PathParam("idOrName") String idOrName, @HeaderParam(ACCEPT_LANGUAGE) String acceptLanguage) {
+    @Operation(summary = "Present a dataset type",
+            description = "Provides one dataset type by numeric id or name.",
+            operationId = "Datasets_getDatasetType")
+    public Response getDatasetTypes(
+            @Parameter(description = "Dataset type numeric id or name.", required = true)
+            @PathParam("idOrName") String idOrName, @HeaderParam(ACCEPT_LANGUAGE) String acceptLanguage) {
         Locale locale = I18nUtil.parseAcceptLanguageHeader(acceptLanguage);
         DatasetType datasetType = null;
         if (StringUtils.isNumeric(idOrName)) {
@@ -5883,7 +6005,12 @@ public Response addDatasetType(@Context ContainerRequestContext crc, String json
     @DELETE
     @AuthRequired
     @Path("datasetTypes/{id}")
-    public Response deleteDatasetType(@Context ContainerRequestContext crc, @PathParam("id") String doomed) {
+    @Operation(summary = "Remove a dataset type",
+            description = "Deletes a non-default dataset type by database id.")
+    @SecurityRequirement(name = "DataverseApiKey")
+    public Response deleteDatasetType(@Context ContainerRequestContext crc,
+            @Parameter(description = "Dataset type database id.", required = true)
+            @PathParam("id") String doomed) {
         AuthenticatedUser user;
         try {
             user = getRequestAuthenticatedUserOrDie(crc);
@@ -5929,7 +6056,14 @@ public Response deleteDatasetType(@Context ContainerRequestContext crc, @PathPar
     @AuthRequired
     @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",
+            description = "Replaces the metadata blocks linked to a dataset type.")
+    @SecurityRequirement(name = "DataverseApiKey")
+    public Response updateDatasetTypeLinksWithMetadataBlocks(@Context ContainerRequestContext crc,
+            @Parameter(description = "Dataset type id or name.", required = true)
+            @PathParam("idOrName") String idOrName,
+            @RequestBody(description = "JSON array of metadata block names to link to the dataset type.")
+            String jsonBody) {
         DatasetType datasetType = null;
         if (StringUtils.isNumeric(idOrName)) {
             try {
@@ -5977,7 +6111,14 @@ public Response updateDatasetTypeLinksWithMetadataBlocks(@Context ContainerReque
     @AuthRequired
     @PUT
     @Path("datasetTypes/{idOrName}/licenses")
-    public Response updateDatasetTypeWithLicenses(@Context ContainerRequestContext crc, @PathParam("idOrName") String idOrName, String jsonBody) {
+    @Operation(summary = "Configure licenses for a dataset type",
+            description = "Replaces the licenses available for a dataset type.")
+    @SecurityRequirement(name = "DataverseApiKey")
+    public Response updateDatasetTypeWithLicenses(@Context ContainerRequestContext crc,
+            @Parameter(description = "Dataset type id or name.", required = true)
+            @PathParam("idOrName") String idOrName,
+            @RequestBody(description = "JSON array of license names or URIs available for the dataset type.")
+            String jsonBody) {
         DatasetType datasetType = null;
         if (StringUtils.isNumeric(idOrName)) {
             try {
@@ -6025,7 +6166,14 @@ public Response updateDatasetTypeWithLicenses(@Context ContainerRequestContext c
     @AuthRequired
     @PUT
     @Path("{identifier}/guestbook")
-    public Response updateDatasetGuestbook(@Context ContainerRequestContext crc, @PathParam("identifier") String identifier, String body) {
+    @Operation(summary = "Assign a guestbook to a dataset",
+            description = "Sets the guestbook used by the selected dataset.")
+    @SecurityRequirement(name = "DataverseApiKey")
+    public Response updateDatasetGuestbook(@Context ContainerRequestContext crc,
+            @Parameter(description = "Dataset id or persistent identifier.", required = true)
+            @PathParam("identifier") String identifier,
+            @RequestBody(description = "Guestbook database id to assign to the dataset.")
+            String body) {
         return response(req -> {
             Dataset dataset = findDatasetOrDie(identifier);
             Long guestbookId = null;
@@ -6051,7 +6199,12 @@ public Response updateDatasetGuestbook(@Context ContainerRequestContext crc, @Pa
     @AuthRequired
     @DELETE
     @Path("{identifier}/guestbook")
-    public Response deleteDatasetGuestbook(@Context ContainerRequestContext crc, @PathParam("identifier") String identifier) {
+    @Operation(summary = "Clear a dataset guestbook",
+            description = "Removes the guestbook assignment from the selected dataset.")
+    @SecurityRequirement(name = "DataverseApiKey")
+    public Response deleteDatasetGuestbook(@Context ContainerRequestContext crc,
+            @Parameter(description = "Dataset id or persistent identifier.", required = true)
+            @PathParam("identifier") String identifier) {
         return response(req -> {
             Dataset dataset = findDatasetOrDie(identifier);
             if (dataset.getGuestbook() != null) {
@@ -6074,7 +6227,13 @@ public Response deleteDatasetGuestbook(@Context ContainerRequestContext crc, @Pa
     @AuthRequired
     @Path("{id}/deleteFiles")
     @Consumes(MediaType.APPLICATION_JSON)
-    public Response deleteDatasetFiles(@Context ContainerRequestContext crc, @PathParam("id") String id,
+    @Operation(summary = "Remove files from a dataset draft",
+            description = "Deletes selected files from the dataset draft and removes physical files that have never been released.")
+    @SecurityRequirement(name = "DataverseApiKey")
+    public Response deleteDatasetFiles(@Context ContainerRequestContext crc,
+            @Parameter(description = "Dataset id or persistent identifier.", required = true)
+            @PathParam("id") String id,
+            @RequestBody(description = "JSON array of data file ids to delete from the dataset draft.")
             JsonArray fileIds) {
         try {
             getRequestAuthenticatedUserOrDie(crc);
@@ -6137,7 +6296,15 @@ public Response deleteDatasetFiles(@Context ContainerRequestContext crc, @PathPa
     @GET
     @AuthRequired
     @Path("{id}/versions/{versionId}/versionNote")
-    public Response getVersionCreationNote(@Context ContainerRequestContext crc, @PathParam("id") String datasetId, @PathParam("versionId") String versionId, @Context UriInfo uriInfo, @Context HttpHeaders headers) throws WrappedResponse {
+    @Operation(summary = "Read a dataset version note",
+            description = "Returns the note stored on the requested dataset version.")
+    @SecurityRequirement(name = "DataverseApiKey")
+    public Response getVersionCreationNote(@Context ContainerRequestContext crc,
+            @Parameter(description = "Dataset id or persistent identifier.", required = true)
+            @PathParam("id") String datasetId,
+            @Parameter(description = "Dataset version id or version label.", required = true)
+            @PathParam("versionId") String versionId,
+            @Context UriInfo uriInfo, @Context HttpHeaders headers) throws WrappedResponse {
 
         return response(req -> {
             DatasetVersion datasetVersion = getDatasetVersionOrDie(req, versionId, findDatasetOrDie(datasetId), uriInfo, headers);
@@ -6152,7 +6319,17 @@ public Response getVersionCreationNote(@Context ContainerRequestContext crc, @Pa
     @PUT
     @AuthRequired
     @Path("{id}/versions/{versionId}/versionNote")
-    public Response addVersionNote(@Context ContainerRequestContext crc, @PathParam("id") String datasetId, @PathParam("versionId") String versionId, String note, @Context UriInfo uriInfo, @Context HttpHeaders headers) throws WrappedResponse {
+    @Operation(summary = "Store a dataset version note",
+            description = "Adds or replaces the note on a draft or superuser-selected published dataset version.")
+    @SecurityRequirement(name = "DataverseApiKey")
+    public Response addVersionNote(@Context ContainerRequestContext crc,
+            @Parameter(description = "Dataset id or persistent identifier.", required = true)
+            @PathParam("id") String datasetId,
+            @Parameter(description = "Dataset version id or version label.", required = true)
+            @PathParam("versionId") String versionId,
+            @RequestBody(description = "Plain text note to store on the dataset version.")
+            String note,
+            @Context UriInfo uriInfo, @Context HttpHeaders headers) throws WrappedResponse {
         if (!FeatureFlags.VERSION_NOTE.enabled()) {
             return notFound(BundleUtil.getStringFromBundle("datasets.api.addVersionNote.notEnabled"));
         }
@@ -6185,7 +6362,15 @@ public Response addVersionNote(@Context ContainerRequestContext crc, @PathParam(
     @DELETE
     @AuthRequired
     @Path("{id}/versions/{versionId}/versionNote")
-    public Response deleteVersionNote(@Context ContainerRequestContext crc, @PathParam("id") String datasetId, @PathParam("versionId") String versionId, @Context UriInfo uriInfo, @Context HttpHeaders headers) throws WrappedResponse {
+    @Operation(summary = "Clear a dataset version note",
+            description = "Deletes the note from a draft or superuser-selected published dataset version.")
+    @SecurityRequirement(name = "DataverseApiKey")
+    public Response deleteVersionNote(@Context ContainerRequestContext crc,
+            @Parameter(description = "Dataset id or persistent identifier.", required = true)
+            @PathParam("id") String datasetId,
+            @Parameter(description = "Dataset version id or version label.", required = true)
+            @PathParam("versionId") String versionId,
+            @Context UriInfo uriInfo, @Context HttpHeaders headers) throws WrappedResponse {
         if(!FeatureFlags.VERSION_NOTE.enabled()) {
             return notFound(BundleUtil.getStringFromBundle("datasets.api.addVersionNote.notEnabled"));
         }
@@ -6208,7 +6393,13 @@ public Response deleteVersionNote(@Context ContainerRequestContext crc, @PathPar
     @AuthRequired
     @Path("{identifier}/assignments/history")
     @Produces({ MediaType.APPLICATION_JSON, "text/csv" })
-    public Response getRoleAssignmentHistory(@Context ContainerRequestContext crc, @PathParam("identifier") String id, @Context HttpHeaders headers) {
+    @Operation(summary = "Read dataset role assignment history",
+            description = "Returns dataset role assignment history as JSON or CSV.")
+    @SecurityRequirement(name = "DataverseApiKey")
+    public Response getRoleAssignmentHistory(@Context ContainerRequestContext crc,
+            @Parameter(description = "Dataset id or persistent identifier.", required = true)
+            @PathParam("identifier") String id,
+            @Context HttpHeaders headers) {
         return response(req -> {
             Dataset dataset = findDatasetOrDie(id);
 
@@ -6223,7 +6414,11 @@ public Response getRoleAssignmentHistory(@Context ContainerRequestContext crc, @
     @AuthRequired
     @Path("{identifier}/files/assignments/history")
     @Produces({ MediaType.APPLICATION_JSON, "text/csv" })
+    @Operation(summary = "Read file role assignment history",
+            description = "Returns file-level role assignment history for a dataset as JSON or CSV.")
+    @SecurityRequirement(name = "DataverseApiKey")
     public Response getFilesRoleAssignmentHistory(@Context ContainerRequestContext crc,
+            @Parameter(description = "Dataset id or persistent identifier.", required = true)
             @PathParam("identifier") String id,
             @Context HttpHeaders headers) {
         return response(req -> {
@@ -6239,8 +6434,13 @@ public Response getFilesRoleAssignmentHistory(@Context ContainerRequestContext c
     @PUT
     @AuthRequired
     @Path("{id}/license")
+    @Operation(summary = "Change a dataset license",
+            description = "Updates the dataset license by name or URI, or applies custom terms.")
+    @SecurityRequirement(name = "DataverseApiKey")
     public Response updateLicense(@Context ContainerRequestContext crc,
+                                  @Parameter(description = "Dataset id or persistent identifier.", required = true)
                                   @PathParam("id") String datasetId,
+                                  @RequestBody(description = "License update request containing a license name, URI, or custom terms.")
                                   LicenseUpdateRequest requestBody) {
         return response(req -> {
             Dataset dataset = findDatasetOrDie(datasetId);
@@ -6273,7 +6473,14 @@ public Response updateLicense(@Context ContainerRequestContext crc,
     @GET
     @AuthRequired
     @Path("{identifier}/storage/quota")
-    public Response getDatasetQuota(@Context ContainerRequestContext crc, @PathParam("identifier") String dvIdtf, @QueryParam("showInherited") boolean showInherited) throws WrappedResponse {
+    @Operation(summary = "Read dataset storage quota",
+            description = "Returns the storage quota for a dataset, optionally including inherited quota values.")
+    @SecurityRequirement(name = "DataverseApiKey")
+    public Response getDatasetQuota(@Context ContainerRequestContext crc,
+            @Parameter(description = "Dataset id or persistent identifier.", required = true)
+            @PathParam("identifier") String dvIdtf,
+            @Parameter(description = "Whether to include inherited quota settings in the response.")
+            @QueryParam("showInherited") boolean showInherited) throws WrappedResponse {
         try {
             Long bytesAllocated = execCommand(new GetDatasetQuotaCommand(createDataverseRequest(getRequestUser(crc)), findDatasetOrDie(dvIdtf), showInherited));
             if (bytesAllocated != null) {
@@ -6288,7 +6495,14 @@ public Response getDatasetQuota(@Context ContainerRequestContext crc, @PathParam
     @PUT
     @AuthRequired
     @Path("{identifier}/storage/quota")
-    public Response setDatasetQuota(@Context ContainerRequestContext crc, @PathParam("identifier") String dvIdtf, String value) throws WrappedResponse {
+    @Operation(summary = "Assign dataset storage quota",
+            description = "Sets the dataset storage quota in bytes.")
+    @SecurityRequirement(name = "DataverseApiKey")
+    public Response setDatasetQuota(@Context ContainerRequestContext crc,
+            @Parameter(description = "Dataset id or persistent identifier.", required = true)
+            @PathParam("identifier") String dvIdtf,
+            @RequestBody(description = "Quota value in bytes.")
+            String value) throws WrappedResponse {
         try {
             Long bytesAllocated; 
             try {
@@ -6306,7 +6520,12 @@ public Response setDatasetQuota(@Context ContainerRequestContext crc, @PathParam
     @DELETE
     @AuthRequired
     @Path("{identifier}/storage/quota")
-    public Response deleteDatasetQuota(@Context ContainerRequestContext crc, @PathParam("identifier") String dvIdtf) throws WrappedResponse {
+    @Operation(summary = "Clear dataset storage quota",
+            description = "Deletes the explicit storage quota for a dataset.")
+    @SecurityRequirement(name = "DataverseApiKey")
+    public Response deleteDatasetQuota(@Context ContainerRequestContext crc,
+            @Parameter(description = "Dataset id or persistent identifier.", required = true)
+            @PathParam("identifier") String dvIdtf) throws WrappedResponse {
         try {
             execCommand(new DeleteDatasetQuotaCommand(createDataverseRequest(getRequestUser(crc)), findDatasetOrDie(dvIdtf)));
             return ok(BundleUtil.getStringFromBundle("dataset.storage.quota.deleted"));
@@ -6327,7 +6546,12 @@ public Response deleteDatasetQuota(@Context ContainerRequestContext crc, @PathPa
     @GET
     @AuthRequired
     @Path("{identifier}/storage/use")
-    public Response getDatasetStorageUse(@Context ContainerRequestContext crc, @PathParam("identifier") String identifier) throws WrappedResponse {
+    @Operation(summary = "Read dataset storage use",
+            description = "Returns the recorded storage use for a dataset.")
+    @SecurityRequirement(name = "DataverseApiKey")
+    public Response getDatasetStorageUse(@Context ContainerRequestContext crc,
+            @Parameter(description = "Dataset id or persistent identifier.", required = true)
+            @PathParam("identifier") String identifier) throws WrappedResponse {
         return response(req -> ok(MessageFormat.format(BundleUtil.getStringFromBundle("dataset.storage.use"),
                 execCommand(new GetDatasetStorageUseCommand(req, findDatasetOrDie(identifier))))), getRequestUser(crc));
     }
@@ -6335,7 +6559,12 @@ public Response getDatasetStorageUse(@Context ContainerRequestContext crc, @Path
     @GET
     @AuthRequired
     @Path("{identifier}/uploadlimits")
-    public Response getUploadLimits(@Context ContainerRequestContext crc, @PathParam("identifier") String dvIdtf,
+    @Operation(summary = "Read dataset upload limits",
+            description = "Returns upload size limits that apply to the selected dataset.")
+    @SecurityRequirement(name = "DataverseApiKey")
+    public Response getUploadLimits(@Context ContainerRequestContext crc,
+            @Parameter(description = "Dataset id or persistent identifier.", required = true)
+            @PathParam("identifier") String dvIdtf,
             @Context UriInfo uriInfo,
             @Context HttpHeaders headers) throws WrappedResponse {
 
diff --git a/src/main/java/edu/harvard/iq/dataverse/api/DataverseFeaturedItems.java b/src/main/java/edu/harvard/iq/dataverse/api/DataverseFeaturedItems.java
index 7fbdd79e3c3..094d30dcd88 100644
--- a/src/main/java/edu/harvard/iq/dataverse/api/DataverseFeaturedItems.java
+++ b/src/main/java/edu/harvard/iq/dataverse/api/DataverseFeaturedItems.java
@@ -14,6 +14,10 @@
 import jakarta.ws.rs.core.Context;
 import jakarta.ws.rs.core.MediaType;
 import jakarta.ws.rs.core.Response;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.Parameter;
+import io.swagger.v3.oas.annotations.security.SecurityRequirement;
+import io.swagger.v3.oas.annotations.tags.Tag;
 import org.glassfish.jersey.media.multipart.FormDataContentDisposition;
 import org.glassfish.jersey.media.multipart.FormDataParam;
 
@@ -24,6 +28,8 @@
 
 @Stateless
 @Path("dataverseFeaturedItems")
+@Tag(name = "Dataverse Featured Items", description = "Manage featured items displayed on dataverse pages.")
+@SecurityRequirement(name = "DataverseApiKey")
 public class DataverseFeaturedItems extends AbstractApiBean {
 
     @Inject
@@ -32,7 +38,11 @@ public class DataverseFeaturedItems extends AbstractApiBean {
     @DELETE
     @AuthRequired
     @Path("{id}")
-    public Response deleteFeaturedItem(@Context ContainerRequestContext crc, @PathParam("id") Long id) {
+    @Operation(summary = "Remove a dataverse featured item",
+            description = "Deletes the featured item with the supplied database id.")
+    public Response deleteFeaturedItem(@Context ContainerRequestContext crc,
+                                       @Parameter(description = "Database id of the featured item to delete.", required = true)
+                                       @PathParam("id") Long id) {
         try {
             DataverseFeaturedItem dataverseFeaturedItem = dataverseFeaturedItemServiceBean.findById(id);
             if (dataverseFeaturedItem == null) {
@@ -49,14 +59,24 @@ public Response deleteFeaturedItem(@Context ContainerRequestContext crc, @PathPa
     @AuthRequired
     @Consumes(MediaType.MULTIPART_FORM_DATA)
     @Path("{id}")
+    @Operation(summary = "Revise a dataverse featured item",
+            description = "Updates text, linked object, display order, and optional image content for a featured item.")
     public Response updateFeaturedItem(@Context ContainerRequestContext crc,
+                                       @Parameter(description = "Database id of the featured item to update.", required = true)
                                        @PathParam("id") Long id,
+                                       @Parameter(description = "Featured item text or link content.")
                                        @FormDataParam("content") String content,
+                                       @Parameter(description = "Featured item type used to resolve an optional linked dataverse object.")
                                        @FormDataParam("type") String type,
+                                       @Parameter(description = "Identifier of the optional dataverse object linked by this featured item.")
                                        @FormDataParam("dvObjectIdentifier") String dvObjectIdtf,
+                                       @Parameter(description = "Display order for the featured item.")
                                        @FormDataParam("displayOrder") int displayOrder,
+                                       @Parameter(description = "Whether to keep the existing featured item image.")
                                        @FormDataParam("keepFile") boolean keepFile,
+                                       @Parameter(description = "Replacement featured item image file.")
                                        @FormDataParam("file") InputStream imageFileInputStream,
+                                       @Parameter(description = "Uploaded image file metadata.")
                                        @FormDataParam("file") FormDataContentDisposition contentDispositionHeader) {
         try {
             DataverseFeaturedItem dataverseFeaturedItem = dataverseFeaturedItemServiceBean.findById(id);
diff --git a/src/main/java/edu/harvard/iq/dataverse/api/Dataverses.java b/src/main/java/edu/harvard/iq/dataverse/api/Dataverses.java
index 0c0aa59057c..a784c567f4a 100644
--- a/src/main/java/edu/harvard/iq/dataverse/api/Dataverses.java
+++ b/src/main/java/edu/harvard/iq/dataverse/api/Dataverses.java
@@ -77,6 +77,11 @@
 import org.glassfish.jersey.media.multipart.FormDataBodyPart;
 import org.glassfish.jersey.media.multipart.FormDataContentDisposition;
 import org.glassfish.jersey.media.multipart.FormDataParam;
+import org.eclipse.microprofile.openapi.annotations.Operation;
+import org.eclipse.microprofile.openapi.annotations.parameters.Parameter;
+import org.eclipse.microprofile.openapi.annotations.parameters.RequestBody;
+import org.eclipse.microprofile.openapi.annotations.security.SecurityRequirement;
+import org.eclipse.microprofile.openapi.annotations.tags.Tag;
 
 import javax.xml.stream.XMLStreamException;
 
@@ -87,6 +92,8 @@
  */
 @Stateless
 @Path("dataverses")
+@Tag(name = "Dataverses", description = "Dataverse collection metadata, datasets, roles, groups, links, templates, storage, and featured content.")
+@SecurityRequirement(name = "DataverseApiKey")
 public class Dataverses extends AbstractApiBean {
 
     private static final Logger logger = Logger.getLogger(Dataverses.class.getCanonicalName());
@@ -129,7 +136,11 @@ public class Dataverses extends AbstractApiBean {
     
     @POST
     @AuthRequired
-    public Response addRoot(@Context ContainerRequestContext crc, String body) {
+    @Operation(summary = "Provision the root dataverse",
+            description = "Creates the root dataverse from a Dataverse JSON payload.")
+    public Response addRoot(@Context ContainerRequestContext crc,
+            @RequestBody(description = "Dataverse JSON for the root collection.")
+            String body) {
         logger.info("Creating root dataverse");
         return addDataverse(crc, body, "");
     }
@@ -137,7 +148,13 @@ public Response addRoot(@Context ContainerRequestContext crc, String body) {
     @POST
     @AuthRequired
     @Path("{identifier}")
-    public Response addDataverse(@Context ContainerRequestContext crc, String body, @PathParam("identifier") String parentIdtf) {
+    @Operation(summary = "Provision a child dataverse",
+            description = "Creates a dataverse under the selected parent and returns the created collection metadata.")
+    public Response addDataverse(@Context ContainerRequestContext crc,
+            @RequestBody(description = "Dataverse JSON including alias, name, contact, metadata block, input level, and facet settings.")
+            String body,
+            @Parameter(description = "Parent dataverse alias, id, or persistent identifier.", required = true)
+            @PathParam("identifier") String parentIdtf) {
         Dataverse newDataverse;
         try {
             newDataverse = parseAndValidateAddDataverseRequestBody(body);
@@ -187,7 +204,13 @@ private Dataverse parseAndValidateAddDataverseRequestBody(String body) throws Js
     @PUT
     @AuthRequired
     @Path("{identifier}")
-    public Response updateDataverse(@Context ContainerRequestContext crc, String body, @PathParam("identifier") String identifier) {
+    @Operation(summary = "Revise a dataverse",
+            description = "Updates dataverse metadata and optional metadata block, input level, and facet settings.")
+    public Response updateDataverse(@Context ContainerRequestContext crc,
+            @RequestBody(description = "Dataverse update JSON with metadata and optional configuration sections.")
+            String body,
+            @Parameter(description = "Dataverse alias, id, or persistent identifier.", required = true)
+            @PathParam("identifier") String identifier) {
         Dataverse dataverse;
         try {
             dataverse = findDataverseOrDie(identifier);
@@ -341,7 +364,13 @@ private List<MetadataBlock> parseNewDataverseMetadataBlocks(JsonArray metadataBl
     @AuthRequired
     @Path("{identifier}/validateDatasetJson")
     @Consumes("application/json")
-    public Response validateDatasetJson(@Context ContainerRequestContext crc, String body, @PathParam("identifier") String idtf) {
+    @Operation(summary = "Validate dataset JSON",
+            description = "Validates a dataset JSON payload against the selected dataverse.")
+    public Response validateDatasetJson(@Context ContainerRequestContext crc,
+            @RequestBody(description = "Dataset JSON to validate.")
+            String body,
+            @Parameter(description = "Dataverse alias, id, or persistent identifier.", required = true)
+            @PathParam("identifier") String idtf) {
         User u = getRequestUser(crc);
         try {
             String validationMessage = execCommand(new ValidateDatasetJsonCommand(createDataverseRequest(u), findDataverseOrDie(idtf), body));
@@ -356,7 +385,11 @@ public Response validateDatasetJson(@Context ContainerRequestContext crc, String
     @AuthRequired
     @Path("{identifier}/datasetSchema")
     @Produces(MediaType.APPLICATION_JSON)
-    public Response getDatasetSchema(@Context ContainerRequestContext crc, @PathParam("identifier") String idtf) {
+    @Operation(summary = "Read dataset schema for a dataverse",
+            description = "Returns the dataset JSON schema generated for the selected dataverse.")
+    public Response getDatasetSchema(@Context ContainerRequestContext crc,
+            @Parameter(description = "Dataverse alias, id, or persistent identifier.", required = true)
+            @PathParam("identifier") String idtf) {
         User u = getRequestUser(crc);
 
         try {
@@ -375,7 +408,15 @@ public Response getDatasetSchema(@Context ContainerRequestContext crc, @PathPara
     @AuthRequired
     @Path("{identifier}/datasets")
     @Consumes("application/json")
-    public Response createDataset(@Context ContainerRequestContext crc, String jsonBody, @PathParam("identifier") String parentIdtf, @QueryParam("doNotValidate") String doNotValidateParam) {
+    @Operation(summary = "Provision a dataset from JSON",
+            description = "Creates a draft dataset in the selected dataverse and returns its id and persistent identifier.")
+    public Response createDataset(@Context ContainerRequestContext crc,
+            @RequestBody(description = "Dataset JSON containing at least one dataset version.")
+            String jsonBody,
+            @Parameter(description = "Dataverse alias, id, or persistent identifier for the dataset owner.", required = true)
+            @PathParam("identifier") String parentIdtf,
+            @Parameter(description = "When true and incomplete metadata is allowed, skip full metadata validation.")
+            @QueryParam("doNotValidate") String doNotValidateParam) {
         try {
             logger.fine("Json is: " + jsonBody);
             User u = getRequestUser(crc);
@@ -452,7 +493,13 @@ public Response createDataset(@Context ContainerRequestContext crc, String jsonB
     @AuthRequired
     @Path("{identifier}/datasets")
     @Consumes("application/ld+json, application/json-ld")
-    public Response createDatasetFromJsonLd(@Context ContainerRequestContext crc, String jsonLDBody, @PathParam("identifier") String parentIdtf) {
+    @Operation(summary = "Provision a dataset from JSON-LD",
+            description = "Creates a draft dataset in the selected dataverse from JSON-LD metadata.")
+    public Response createDatasetFromJsonLd(@Context ContainerRequestContext crc,
+            @RequestBody(description = "JSON-LD dataset metadata.")
+            String jsonLDBody,
+            @Parameter(description = "Dataverse alias, id, or persistent identifier for the dataset owner.", required = true)
+            @PathParam("identifier") String parentIdtf) {
         try {
             User u = getRequestUser(crc);
             Dataverse owner = findDataverseOrDie(parentIdtf);
@@ -496,7 +543,17 @@ public Response createDatasetFromJsonLd(@Context ContainerRequestContext crc, St
     @POST
     @AuthRequired
     @Path("{identifier}/datasets/:import")
-    public Response importDataset(@Context ContainerRequestContext crc, String jsonBody, @PathParam("identifier") String parentIdtf, @QueryParam("pid") String pidParam, @QueryParam("release") String releaseParam) {
+    @Operation(summary = "Import a dataset from JSON",
+            description = "Imports a dataset into the selected dataverse, optionally assigning a supplied PID and release state.")
+    public Response importDataset(@Context ContainerRequestContext crc,
+            @RequestBody(description = "Dataset JSON to import.")
+            String jsonBody,
+            @Parameter(description = "Dataverse alias, id, or persistent identifier for the dataset owner.", required = true)
+            @PathParam("identifier") String parentIdtf,
+            @Parameter(description = "Persistent identifier to assign to the imported dataset.")
+            @QueryParam("pid") String pidParam,
+            @Parameter(description = "When true, import the dataset as released.")
+            @QueryParam("release") String releaseParam) {
         try {
             User u = getRequestUser(crc);
             if (!u.isSuperuser()) {
@@ -577,7 +634,17 @@ public Response importDataset(@Context ContainerRequestContext crc, String jsonB
     @POST
     @AuthRequired
     @Path("{identifier}/datasets/:importddi")
-    public Response importDatasetDdi(@Context ContainerRequestContext crc, String xml, @PathParam("identifier") String parentIdtf, @QueryParam("pid") String pidParam, @QueryParam("release") String releaseParam) {
+    @Operation(summary = "Import a dataset from DDI XML",
+            description = "Converts DDI XML to dataset metadata and imports it into the selected dataverse.")
+    public Response importDatasetDdi(@Context ContainerRequestContext crc,
+            @RequestBody(description = "DDI XML document to import.")
+            String xml,
+            @Parameter(description = "Dataverse alias, id, or persistent identifier for the dataset owner.", required = true)
+            @PathParam("identifier") String parentIdtf,
+            @Parameter(description = "Persistent identifier to assign to the imported dataset.")
+            @QueryParam("pid") String pidParam,
+            @Parameter(description = "When true, import the dataset as released.")
+            @QueryParam("release") String releaseParam) {
         try {
             User u = getRequestUser(crc);
             if (!u.isSuperuser()) {
@@ -653,7 +720,13 @@ public Response importDatasetDdi(@Context ContainerRequestContext crc, String xm
     @AuthRequired
     @Path("{identifier}/datasets/:startmigration")
     @Consumes("application/ld+json, application/json-ld")
-    public Response recreateDataset(@Context ContainerRequestContext crc, String jsonLDBody, @PathParam("identifier") String parentIdtf) {
+    @Operation(summary = "Start migrated dataset recreation",
+            description = "Creates a draft dataset from published JSON-LD metadata for a migration workflow.")
+    public Response recreateDataset(@Context ContainerRequestContext crc,
+            @RequestBody(description = "Published dataset JSON-LD metadata to recreate as a draft.")
+            String jsonLDBody,
+            @Parameter(description = "Dataverse alias, id, or persistent identifier for the dataset owner.", required = true)
+            @PathParam("identifier") String parentIdtf) {
         try {
             User u = getRequestUser(crc);
             if (!u.isSuperuser()) {
@@ -717,10 +790,16 @@ private Dataset parseDataset(String datasetJson) throws WrappedResponse {
     @GET
     @AuthRequired
     @Path("{identifier}")
+    @Operation(summary = "Read a dataverse",
+            description = "Returns dataverse metadata with optional owner and child-count information.")
     public Response getDataverse(@Context ContainerRequestContext crc,
+                                 @Parameter(description = "Dataverse alias, id, or persistent identifier.", required = true)
                                  @PathParam("identifier") String idtf,
+                                 @Parameter(description = "Whether to include owner information.")
                                  @QueryParam("returnOwners") boolean returnOwners,
+                                 @Parameter(description = "Whether to include the number of child objects.")
                                  @QueryParam("returnChildCount") boolean returnChildCount,
+                                 @Parameter(description = "Whether to include email fields when the caller has permission to ignore the email-exclusion setting.")
                                  @QueryParam("ignoreSettingExcludeEmailFromExport") Boolean ignoreSettingToExcludeEmailFromExport) {
         return response(req -> {
             Dataverse dataverse = execCommand(new GetDataverseCommand(req, findDataverseOrDie(idtf)));
@@ -740,7 +819,11 @@ public Response getDataverse(@Context ContainerRequestContext crc,
     @DELETE
     @AuthRequired
     @Path("{identifier}")
-    public Response deleteDataverse(@Context ContainerRequestContext crc, @PathParam("identifier") String idtf) {
+    @Operation(summary = "Remove a dataverse",
+            description = "Deletes the selected dataverse collection.")
+    public Response deleteDataverse(@Context ContainerRequestContext crc,
+            @Parameter(description = "Dataverse alias, id, or persistent identifier.", required = true)
+            @PathParam("identifier") String idtf) {
         return response(req -> {
             execCommand(new DeleteDataverseCommand(req, findDataverseOrDie(idtf)));
             return ok("Dataverse " + idtf + " deleted");
@@ -757,8 +840,15 @@ public Response deleteDataverse(@Context ContainerRequestContext crc, @PathParam
     @PUT
     @AuthRequired
     @Path("{identifier}/attribute/{attribute}")
-    public Response updateAttribute(@Context ContainerRequestContext crc, @PathParam("identifier") String identifier,
-                                    @PathParam("attribute") String attribute, @QueryParam("value") String value) {
+    @Operation(summary = "Change a dataverse attribute",
+            description = "Updates one supported dataverse attribute value.")
+    public Response updateAttribute(@Context ContainerRequestContext crc,
+                                    @Parameter(description = "Dataverse alias, id, or persistent identifier.", required = true)
+                                    @PathParam("identifier") String identifier,
+                                    @Parameter(description = "Dataverse attribute name to change.", required = true)
+                                    @PathParam("attribute") String attribute,
+                                    @Parameter(description = "New attribute value.")
+                                    @QueryParam("value") String value) {
         try {
             Dataverse dataverse = findDataverseOrDie(identifier);
             Object formattedValue = formatAttributeValue(attribute, value);
@@ -779,7 +869,11 @@ private Object formatAttributeValue(String attribute, String value) throws Wrapp
     @GET
     @AuthRequired
     @Path("{identifier}/inputLevels")
-    public Response getInputLevels(@Context ContainerRequestContext crc, @PathParam("identifier") String identifier) {
+    @Operation(summary = "Read dataverse input levels",
+            description = "Returns dataset field input-level settings for a dataverse.")
+    public Response getInputLevels(@Context ContainerRequestContext crc,
+            @Parameter(description = "Dataverse alias, id, or persistent identifier.", required = true)
+            @PathParam("identifier") String identifier) {
         try {
             Dataverse dataverse = findDataverseOrDie(identifier);
             List<DataverseFieldTypeInputLevel> inputLevels = execCommand(new ListDataverseInputLevelsCommand(createDataverseRequest(getRequestUser(crc)), dataverse));
@@ -792,7 +886,13 @@ public Response getInputLevels(@Context ContainerRequestContext crc, @PathParam(
     @PUT
     @AuthRequired
     @Path("{identifier}/inputLevels")
-    public Response updateInputLevels(@Context ContainerRequestContext crc, @PathParam("identifier") String identifier, String jsonBody) {
+    @Operation(summary = "Assign dataverse input levels",
+            description = "Replaces dataset field input-level settings for a dataverse.")
+    public Response updateInputLevels(@Context ContainerRequestContext crc,
+            @Parameter(description = "Dataverse alias, id, or persistent identifier.", required = true)
+            @PathParam("identifier") String identifier,
+            @RequestBody(description = "JSON array of input-level settings for dataset fields.")
+            String jsonBody) {
         try {
             Dataverse dataverse = findDataverseOrDie(identifier);
             List<DataverseFieldTypeInputLevel> newInputLevels = parseInputLevels(Json.createReader(new StringReader(jsonBody)).readArray(), dataverse);
@@ -856,7 +956,13 @@ private List<DatasetFieldType> parseFacets(JsonArray facetsArray) throws Wrapped
     @DELETE
     @AuthRequired
     @Path("{linkingDataverseId}/deleteLink/{linkedDataverseId}")
-    public Response deleteDataverseLinkingDataverse(@Context ContainerRequestContext crc, @PathParam("linkingDataverseId") String linkingDataverseId, @PathParam("linkedDataverseId") String linkedDataverseId) {
+    @Operation(summary = "Remove a dataverse link",
+            description = "Deletes a link from one dataverse to another linked dataverse.")
+    public Response deleteDataverseLinkingDataverse(@Context ContainerRequestContext crc,
+            @Parameter(description = "Alias or id of the dataverse containing the link.", required = true)
+            @PathParam("linkingDataverseId") String linkingDataverseId,
+            @Parameter(description = "Alias or id of the linked dataverse to remove.", required = true)
+            @PathParam("linkedDataverseId") String linkedDataverseId) {
         boolean index = true;
         return response(req -> {
             execCommand(new DeleteDataverseLinkingDataverseCommand(req, findDataverseOrDie(linkingDataverseId), findDataverseLinkingDataverseOrDie(linkingDataverseId, linkedDataverseId), index));
@@ -867,10 +973,16 @@ public Response deleteDataverseLinkingDataverse(@Context ContainerRequestContext
     @GET
     @AuthRequired
     @Path("{identifier}/metadatablocks")
+    @Operation(summary = "Read dataverse metadata blocks",
+            description = "Lists metadata blocks configured for a dataverse, optionally including dataset field types.")
     public Response listMetadataBlocks(@Context ContainerRequestContext crc,
+                                       @Parameter(description = "Dataverse alias, id, or persistent identifier.", required = true)
                                        @PathParam("identifier") String dvIdtf,
+                                       @Parameter(description = "When true, include only metadata blocks displayed on dataset creation.")
                                        @QueryParam("onlyDisplayedOnCreate") boolean onlyDisplayedOnCreate,
+                                       @Parameter(description = "Whether to include dataset field type definitions.")
                                        @QueryParam("returnDatasetFieldTypes") boolean returnDatasetFieldTypes,
+                                       @Parameter(description = "Dataset type name used to filter metadata blocks.")
                                        @QueryParam("datasetType") String datasetTypeIn) {
         try {
             Dataverse dataverse = findDataverseOrDie(dvIdtf);
@@ -893,7 +1005,13 @@ public Response listMetadataBlocks(@Context ContainerRequestContext crc,
     @AuthRequired
     @Path("{identifier}/metadatablocks")
     @Produces(MediaType.APPLICATION_JSON)
-    public Response setMetadataBlocks(@Context ContainerRequestContext crc, @PathParam("identifier") String dvIdtf, String blockIds) {
+    @Operation(summary = "Assign metadata blocks to a dataverse",
+            description = "Replaces the metadata blocks configured directly on a dataverse.")
+    public Response setMetadataBlocks(@Context ContainerRequestContext crc,
+            @Parameter(description = "Dataverse alias, id, or persistent identifier.", required = true)
+            @PathParam("identifier") String dvIdtf,
+            @RequestBody(description = "JSON array of metadata block ids or names.")
+            String blockIds) {
 
         List<MetadataBlock> blocks = new LinkedList<>();
         try {
@@ -922,7 +1040,11 @@ public Response setMetadataBlocks(@Context ContainerRequestContext crc, @PathPar
     @GET
     @AuthRequired
     @Path("{identifier}/metadatablocks/:isRoot")
-    public Response getMetadataRoot_legacy(@Context ContainerRequestContext crc, @PathParam("identifier") String dvIdtf) {
+    @Operation(summary = "Read metadata-block root status through legacy route",
+            description = "Returns whether a dataverse is a metadata-block root using the legacy route.")
+    public Response getMetadataRoot_legacy(@Context ContainerRequestContext crc,
+            @Parameter(description = "Dataverse alias, id, or persistent identifier.", required = true)
+            @PathParam("identifier") String dvIdtf) {
         return getMetadataRoot(crc, dvIdtf);
     }
 
@@ -930,7 +1052,11 @@ public Response getMetadataRoot_legacy(@Context ContainerRequestContext crc, @Pa
     @AuthRequired
     @Path("{identifier}/metadatablocks/isRoot")
     @Produces(MediaType.APPLICATION_JSON)
-    public Response getMetadataRoot(@Context ContainerRequestContext crc, @PathParam("identifier") String dvIdtf) {
+    @Operation(summary = "Read metadata-block root status",
+            description = "Returns whether a dataverse is a metadata-block root.")
+    public Response getMetadataRoot(@Context ContainerRequestContext crc,
+            @Parameter(description = "Dataverse alias, id, or persistent identifier.", required = true)
+            @PathParam("identifier") String dvIdtf) {
         return response(req -> {
             final Dataverse dataverse = findDataverseOrDie(dvIdtf);
             if (permissionSvc.request(req)
@@ -948,7 +1074,13 @@ public Response getMetadataRoot(@Context ContainerRequestContext crc, @PathParam
     @Path("{identifier}/metadatablocks/:isRoot")
     @Produces(MediaType.APPLICATION_JSON)
     @Consumes(MediaType.WILDCARD)
-    public Response setMetadataRoot_legacy(@Context ContainerRequestContext crc, @PathParam("identifier") String dvIdtf, String body) {
+    @Operation(summary = "Set metadata-block root status through legacy route",
+            description = "Changes whether a dataverse is a metadata-block root using the legacy route.")
+    public Response setMetadataRoot_legacy(@Context ContainerRequestContext crc,
+            @Parameter(description = "Dataverse alias, id, or persistent identifier.", required = true)
+            @PathParam("identifier") String dvIdtf,
+            @RequestBody(description = "Boolean text indicating whether the dataverse is a metadata-block root.")
+            String body) {
         return setMetadataRoot(crc, dvIdtf, body);
     }
 
@@ -957,7 +1089,13 @@ public Response setMetadataRoot_legacy(@Context ContainerRequestContext crc, @Pa
     @Path("{identifier}/metadatablocks/isRoot")
     @Produces(MediaType.APPLICATION_JSON)
     @Consumes(MediaType.WILDCARD)
-    public Response setMetadataRoot(@Context ContainerRequestContext crc, @PathParam("identifier") String dvIdtf, String body) {
+    @Operation(summary = "Assign metadata-block root status",
+            description = "Changes whether a dataverse is a metadata-block root.")
+    public Response setMetadataRoot(@Context ContainerRequestContext crc,
+            @Parameter(description = "Dataverse alias, id, or persistent identifier.", required = true)
+            @PathParam("identifier") String dvIdtf,
+            @RequestBody(description = "Boolean text indicating whether the dataverse is a metadata-block root.")
+            String body) {
         return response(req -> {
             final boolean root = parseBooleanOrDie(body);
             final Dataverse dataverse = findDataverseOrDie(dvIdtf);
@@ -972,8 +1110,12 @@ public Response setMetadataRoot(@Context ContainerRequestContext crc, @PathParam
     /**
      * return list of facets for the dataverse with alias `dvIdtf`
      */
+    @Operation(summary = "Read dataverse facets",
+            description = "Lists dataset field facets configured for a dataverse, optionally including detailed facet metadata.")
     public Response listFacets(@Context ContainerRequestContext crc,
+                               @Parameter(description = "Dataverse alias, id, or persistent identifier.", required = true)
                                @PathParam("identifier") String dvIdtf,
+                               @Parameter(description = "Whether to include detailed facet metadata.")
                                @QueryParam("returnDetails") boolean returnDetails) {
         try {
             User user = getRequestUser(crc);
@@ -1002,7 +1144,13 @@ public Response listFacets(@Context ContainerRequestContext crc,
     Allows user to get the collections that are featured by a given collection
     probably more for SPA than end user
     */
-    public Response getFeaturedDataverses(@Context ContainerRequestContext crc, @PathParam("identifier") String dvIdtf,  String dvAliases) {
+    @Operation(summary = "Read featured dataverses",
+            description = "Lists aliases for dataverses featured by the selected dataverse.")
+    public Response getFeaturedDataverses(@Context ContainerRequestContext crc,
+            @Parameter(description = "Dataverse alias, id, or persistent identifier.", required = true)
+            @PathParam("identifier") String dvIdtf,
+            @RequestBody(description = "Unused request body accepted by the endpoint.")
+            String dvAliases) {
 
         try {
             User u = getRequestUser(crc);
@@ -1026,7 +1174,13 @@ public Response getFeaturedDataverses(@Context ContainerRequestContext crc, @Pat
      * Allows user to set featured dataverses - must have edit dataverse permission
      *
      */
-    public Response setFeaturedDataverses(@Context ContainerRequestContext crc, @PathParam("identifier") String dvIdtf,  String dvAliases) {
+    @Operation(summary = "Assign featured dataverses",
+            description = "Adds eligible child or linked dataverses to the featured list for a dataverse.")
+    public Response setFeaturedDataverses(@Context ContainerRequestContext crc,
+            @Parameter(description = "Dataverse alias, id, or persistent identifier.", required = true)
+            @PathParam("identifier") String dvIdtf,
+            @RequestBody(description = "JSON array of dataverse aliases to feature.")
+            String dvAliases) {
         List<Dataverse> dvsFromInput = new LinkedList<>();
 
 
@@ -1088,7 +1242,11 @@ public Response setFeaturedDataverses(@Context ContainerRequestContext crc, @Pat
     @DELETE
     @AuthRequired
     @Path("{identifier}/featured")
-    public Response deleteFeaturedCollections(@Context ContainerRequestContext crc, @PathParam("identifier") String dvIdtf) throws WrappedResponse {
+    @Operation(summary = "Clear featured dataverses",
+            description = "Removes all featured dataverses from the selected dataverse.")
+    public Response deleteFeaturedCollections(@Context ContainerRequestContext crc,
+            @Parameter(description = "Dataverse alias, id, or persistent identifier.", required = true)
+            @PathParam("identifier") String dvIdtf) throws WrappedResponse {
         try {
             Dataverse dataverse = findDataverseOrDie(dvIdtf);
             List<Dataverse> featuredTarget = new ArrayList<>();
@@ -1110,7 +1268,13 @@ public Response deleteFeaturedCollections(@Context ContainerRequestContext crc,
      * where foo.json contains a list of datasetField names, works as expected
      * (judging by the UI). This triggers a 500 when '-d @foo.json' is used.
      */
-    public Response setFacets(@Context ContainerRequestContext crc, @PathParam("identifier") String dvIdtf, String facetIds) {
+    @Operation(summary = "Assign dataverse facets",
+            description = "Replaces the dataset field facets configured directly on a dataverse.")
+    public Response setFacets(@Context ContainerRequestContext crc,
+            @Parameter(description = "Dataverse alias, id, or persistent identifier.", required = true)
+            @PathParam("identifier") String dvIdtf,
+            @RequestBody(description = "JSON array of dataset field type names to use as facets.")
+            String facetIds) {
         JsonArray jsonArray = Util.asJsonArray(facetIds);
         List<DatasetFieldType> facets;
         try {
@@ -1134,7 +1298,11 @@ public Response setFacets(@Context ContainerRequestContext crc, @PathParam("iden
     @AuthRequired
     @Path("{identifier}/metadatablockfacets")
     @Produces(MediaType.APPLICATION_JSON)
-    public Response listMetadataBlockFacets(@Context ContainerRequestContext crc, @PathParam("identifier") String dvIdtf) {
+    @Operation(summary = "Read metadata block facets",
+            description = "Returns metadata block facet settings for a dataverse.")
+    public Response listMetadataBlockFacets(@Context ContainerRequestContext crc,
+            @Parameter(description = "Dataverse alias, id, or persistent identifier.", required = true)
+            @PathParam("identifier") String dvIdtf) {
         try {
             User u = getRequestUser(crc);
             DataverseRequest request = createDataverseRequest(u);
@@ -1155,7 +1323,13 @@ public Response listMetadataBlockFacets(@Context ContainerRequestContext crc, @P
     @Path("{identifier}/metadatablockfacets")
     @Consumes(MediaType.APPLICATION_JSON)
     @Produces(MediaType.APPLICATION_JSON)
-    public Response setMetadataBlockFacets(@Context ContainerRequestContext crc, @PathParam("identifier") String dvIdtf, List<String> metadataBlockNames) {
+    @Operation(summary = "Assign metadata block facets",
+            description = "Replaces metadata block facets on a dataverse that is a metadata-block-facet root.")
+    public Response setMetadataBlockFacets(@Context ContainerRequestContext crc,
+            @Parameter(description = "Dataverse alias, id, or persistent identifier.", required = true)
+            @PathParam("identifier") String dvIdtf,
+            @RequestBody(description = "JSON array of metadata block names to use as facets.")
+            List<String> metadataBlockNames) {
         try {
             Dataverse dataverse = findDataverseOrDie(dvIdtf);
 
@@ -1189,7 +1363,13 @@ public Response setMetadataBlockFacets(@Context ContainerRequestContext crc, @Pa
     @Path("{identifier}/metadatablockfacets/isRoot")
     @Consumes(MediaType.APPLICATION_JSON)
     @Produces(MediaType.APPLICATION_JSON)
-    public Response updateMetadataBlockFacetsRoot(@Context ContainerRequestContext crc, @PathParam("identifier") String dvIdtf, String body) {
+    @Operation(summary = "Assign metadata block facet root status",
+            description = "Changes whether a dataverse is a metadata-block-facet root.")
+    public Response updateMetadataBlockFacetsRoot(@Context ContainerRequestContext crc,
+            @Parameter(description = "Dataverse alias, id, or persistent identifier.", required = true)
+            @PathParam("identifier") String dvIdtf,
+            @RequestBody(description = "Boolean text indicating whether the dataverse is a metadata-block-facet root.")
+            String body) {
         try {
             final boolean blockFacetsRoot = parseBooleanOrDie(body);
             Dataverse dataverse = findDataverseOrDie(dvIdtf);
@@ -1212,7 +1392,11 @@ public Response updateMetadataBlockFacetsRoot(@Context ContainerRequestContext c
     @GET
     @AuthRequired
     @Path("{identifier}/contents")
-    public Response listContent(@Context ContainerRequestContext crc, @PathParam("identifier") String dvIdtf) throws WrappedResponse {
+    @Operation(summary = "Read dataverse contents",
+            description = "Lists direct child dataverses and datasets for a dataverse.")
+    public Response listContent(@Context ContainerRequestContext crc,
+            @Parameter(description = "Dataverse alias, id, or persistent identifier.", required = true)
+            @PathParam("identifier") String dvIdtf) throws WrappedResponse {
 
         DvObject.Visitor<JsonObjectBuilder> ser = new DvObject.Visitor<JsonObjectBuilder>() {
             @Override
@@ -1244,7 +1428,13 @@ public JsonObjectBuilder visit(DataFile df) {
     @GET
     @AuthRequired
     @Path("{identifier}/storagesize")
-    public Response getStorageSize(@Context ContainerRequestContext crc, @PathParam("identifier") String dvIdtf, @QueryParam("includeCached") boolean includeCached) throws WrappedResponse {
+    @Operation(summary = "Read dataverse storage size",
+            description = "Returns the storage size for a dataverse, optionally including cached size data.")
+    public Response getStorageSize(@Context ContainerRequestContext crc,
+            @Parameter(description = "Dataverse alias, id, or persistent identifier.", required = true)
+            @PathParam("identifier") String dvIdtf,
+            @Parameter(description = "Whether to include cached storage size values.")
+            @QueryParam("includeCached") boolean includeCached) throws WrappedResponse {
                 
         return response(req -> ok(MessageFormat.format(BundleUtil.getStringFromBundle("dataverse.datasize"),
                 execCommand(new GetDataverseStorageSizeCommand(req, findDataverseOrDie(dvIdtf), includeCached)))), getRequestUser(crc));
@@ -1253,7 +1443,13 @@ public Response getStorageSize(@Context ContainerRequestContext crc, @PathParam(
     @GET
     @AuthRequired
     @Path("{identifier}/storage/quota")
-    public Response getCollectionQuota(@Context ContainerRequestContext crc, @PathParam("identifier") String dvIdtf, @QueryParam("showInherited") boolean showInherited) throws WrappedResponse {
+    @Operation(summary = "Read dataverse storage quota",
+            description = "Returns the storage quota for a dataverse, optionally including inherited quota values.")
+    public Response getCollectionQuota(@Context ContainerRequestContext crc,
+            @Parameter(description = "Dataverse alias, id, or persistent identifier.", required = true)
+            @PathParam("identifier") String dvIdtf,
+            @Parameter(description = "Whether to include inherited quota settings in the response.")
+            @QueryParam("showInherited") boolean showInherited) throws WrappedResponse {
         try {
             Long bytesAllocated = execCommand(new GetCollectionQuotaCommand(createDataverseRequest(getRequestUser(crc)), findDataverseOrDie(dvIdtf), showInherited));
             if (bytesAllocated != null) {
@@ -1268,7 +1464,13 @@ public Response getCollectionQuota(@Context ContainerRequestContext crc, @PathPa
     @PUT
     @AuthRequired
     @Path("{identifier}/storage/quota")
-    public Response setCollectionQuota(@Context ContainerRequestContext crc, @PathParam("identifier") String dvIdtf, String value) throws WrappedResponse {
+    @Operation(summary = "Assign dataverse storage quota",
+            description = "Sets the dataverse storage quota in bytes.")
+    public Response setCollectionQuota(@Context ContainerRequestContext crc,
+            @Parameter(description = "Dataverse alias, id, or persistent identifier.", required = true)
+            @PathParam("identifier") String dvIdtf,
+            @RequestBody(description = "Quota value in bytes.")
+            String value) throws WrappedResponse {
         try {
             Long bytesAllocated; 
             try {
@@ -1286,7 +1488,11 @@ public Response setCollectionQuota(@Context ContainerRequestContext crc, @PathPa
     @DELETE
     @AuthRequired
     @Path("{identifier}/storage/quota")
-    public Response deleteCollectionQuota(@Context ContainerRequestContext crc, @PathParam("identifier") String dvIdtf) throws WrappedResponse {
+    @Operation(summary = "Clear dataverse storage quota",
+            description = "Deletes the explicit storage quota for a dataverse.")
+    public Response deleteCollectionQuota(@Context ContainerRequestContext crc,
+            @Parameter(description = "Dataverse alias, id, or persistent identifier.", required = true)
+            @PathParam("identifier") String dvIdtf) throws WrappedResponse {
         try {
             execCommand(new DeleteCollectionQuotaCommand(createDataverseRequest(getRequestUser(crc)), findDataverseOrDie(dvIdtf)));
             return ok(BundleUtil.getStringFromBundle("dataverse.storage.quota.deleted"));
@@ -1307,7 +1513,11 @@ public Response deleteCollectionQuota(@Context ContainerRequestContext crc, @Pat
     @GET
     @AuthRequired
     @Path("{identifier}/storage/use")
-    public Response getCollectionStorageUse(@Context ContainerRequestContext crc, @PathParam("identifier") String identifier) throws WrappedResponse {
+    @Operation(summary = "Read dataverse storage use",
+            description = "Returns the recorded storage use for a dataverse.")
+    public Response getCollectionStorageUse(@Context ContainerRequestContext crc,
+            @Parameter(description = "Dataverse alias, id, or persistent identifier.", required = true)
+            @PathParam("identifier") String identifier) throws WrappedResponse {
         return response(req -> ok(MessageFormat.format(BundleUtil.getStringFromBundle("dataverse.storage.use"),
                 execCommand(new GetCollectionStorageUseCommand(req, findDataverseOrDie(identifier))))), getRequestUser(crc));
     }
@@ -1315,7 +1525,11 @@ public Response getCollectionStorageUse(@Context ContainerRequestContext crc, @P
     @GET
     @AuthRequired
     @Path("{identifier}/roles")
-    public Response listRoles(@Context ContainerRequestContext crc, @PathParam("identifier") String dvIdtf) {
+    @Operation(summary = "Read dataverse roles",
+            description = "Lists roles available on a dataverse.")
+    public Response listRoles(@Context ContainerRequestContext crc,
+            @Parameter(description = "Dataverse alias, id, or persistent identifier.", required = true)
+            @PathParam("identifier") String dvIdtf) {
         return response(req -> ok(
                 execCommand(new ListRolesCommand(req, findDataverseOrDie(dvIdtf)))
                         .stream().map(r -> json(r))
@@ -1326,14 +1540,24 @@ public Response listRoles(@Context ContainerRequestContext crc, @PathParam("iden
     @POST
     @AuthRequired
     @Path("{identifier}/roles")
-    public Response createRole(@Context ContainerRequestContext crc, RoleDTO roleDto, @PathParam("identifier") String dvIdtf) {
+    @Operation(summary = "Provision a dataverse role",
+            description = "Creates a role scoped to the selected dataverse.")
+    public Response createRole(@Context ContainerRequestContext crc,
+            @RequestBody(description = "Role definition containing alias, name, description, and permissions.")
+            RoleDTO roleDto,
+            @Parameter(description = "Dataverse alias, id, or persistent identifier.", required = true)
+            @PathParam("identifier") String dvIdtf) {
         return response(req -> ok(json(execCommand(new CreateRoleCommand(roleDto.asRole(), req, findDataverseOrDie(dvIdtf))))), getRequestUser(crc));
     }
 
     @GET
     @AuthRequired
     @Path("{identifier}/assignments")
-    public Response listAssignments(@Context ContainerRequestContext crc, @PathParam("identifier") String dvIdtf) {
+    @Operation(summary = "Read dataverse role assignments",
+            description = "Lists role assignments defined on a dataverse.")
+    public Response listAssignments(@Context ContainerRequestContext crc,
+            @Parameter(description = "Dataverse alias, id, or persistent identifier.", required = true)
+            @PathParam("identifier") String dvIdtf) {
         return response(req -> ok(
                 execCommand(new ListRoleAssignments(req, findDataverseOrDie(dvIdtf)))
                         .stream()
@@ -1345,7 +1569,15 @@ public Response listAssignments(@Context ContainerRequestContext crc, @PathParam
     @POST
     @AuthRequired
     @Path("{identifier}/assignments")
-    public Response createAssignment(@Context ContainerRequestContext crc, RoleAssignmentDTO ra, @PathParam("identifier") String dvIdtf, @QueryParam("key") String apiKey) {
+    @Operation(summary = "Grant a dataverse role assignment",
+            description = "Assigns a role to a role assignee on a dataverse.")
+    public Response createAssignment(@Context ContainerRequestContext crc,
+            @RequestBody(description = "Role assignment containing assignee identifier and role alias.")
+            RoleAssignmentDTO ra,
+            @Parameter(description = "Dataverse alias, id, or persistent identifier.", required = true)
+            @PathParam("identifier") String dvIdtf,
+            @Parameter(hidden = true)
+            @QueryParam("key") String apiKey) {
 
         try {
             final DataverseRequest req = createDataverseRequest(getRequestUser(crc));
@@ -1384,7 +1616,13 @@ public Response createAssignment(@Context ContainerRequestContext crc, RoleAssig
     @DELETE
     @AuthRequired
     @Path("{identifier}/assignments/{id}")
-    public Response deleteAssignment(@Context ContainerRequestContext crc, @PathParam("id") long assignmentId, @PathParam("identifier") String dvIdtf) {
+    @Operation(summary = "Remove a dataverse role assignment",
+            description = "Revokes a role assignment from the selected dataverse.")
+    public Response deleteAssignment(@Context ContainerRequestContext crc,
+            @Parameter(description = "Role assignment database id.", required = true)
+            @PathParam("id") long assignmentId,
+            @Parameter(description = "Dataverse alias, id, or persistent identifier.", required = true)
+            @PathParam("identifier") String dvIdtf) {
         RoleAssignment ra = em.find(RoleAssignment.class, assignmentId);
         if (ra != null) {
             try {
@@ -1404,7 +1642,11 @@ public Response deleteAssignment(@Context ContainerRequestContext crc, @PathPara
     @POST
     @AuthRequired
     @Path("{identifier}/actions/:publish")
-    public Response publishDataverse(@Context ContainerRequestContext crc, @PathParam("identifier") String dvIdtf) {
+    @Operation(summary = "Publish a dataverse",
+            description = "Publishes the selected dataverse collection.")
+    public Response publishDataverse(@Context ContainerRequestContext crc,
+            @Parameter(description = "Dataverse alias, id, or persistent identifier.", required = true)
+            @PathParam("identifier") String dvIdtf) {
         try {
             Dataverse dv = findDataverseOrDie(dvIdtf);
             return ok(json(execCommand(new PublishDataverseCommand(createDataverseRequest(getRequestAuthenticatedUserOrDie(crc)), dv))));
@@ -1417,7 +1659,13 @@ public Response publishDataverse(@Context ContainerRequestContext crc, @PathPara
     @POST
     @AuthRequired
     @Path("{identifier}/groups/")
-    public Response createExplicitGroup(@Context ContainerRequestContext crc, ExplicitGroupDTO dto, @PathParam("identifier") String dvIdtf) {
+    @Operation(summary = "Provision an explicit group",
+            description = "Creates an explicit group owned by a dataverse.")
+    public Response createExplicitGroup(@Context ContainerRequestContext crc,
+            @RequestBody(description = "Explicit group definition.")
+            ExplicitGroupDTO dto,
+            @Parameter(description = "Dataverse alias, id, or persistent identifier.", required = true)
+            @PathParam("identifier") String dvIdtf) {
         return response(req -> {
             ExplicitGroupProvider prv = explicitGroupSvc.getProvider();
             ExplicitGroup newGroup = dto.apply(prv.makeGroup());
@@ -1432,7 +1680,13 @@ public Response createExplicitGroup(@Context ContainerRequestContext crc, Explic
     @GET
     @AuthRequired
     @Path("{identifier}/groups/")
-    public Response listGroups(@Context ContainerRequestContext crc, @PathParam("identifier") String dvIdtf, @QueryParam("key") String apiKey) {
+    @Operation(summary = "Read explicit groups",
+            description = "Lists explicit groups owned by a dataverse.")
+    public Response listGroups(@Context ContainerRequestContext crc,
+            @Parameter(description = "Dataverse alias, id, or persistent identifier.", required = true)
+            @PathParam("identifier") String dvIdtf,
+            @Parameter(hidden = true)
+            @QueryParam("key") String apiKey) {
         return response(req -> ok(
                 execCommand(new ListExplicitGroupsCommand(req, findDataverseOrDie(dvIdtf)))
                         .stream().map(eg -> json(eg))
@@ -1443,8 +1697,12 @@ public Response listGroups(@Context ContainerRequestContext crc, @PathParam("ide
     @GET
     @AuthRequired
     @Path("{identifier}/groups/{aliasInOwner}")
+    @Operation(summary = "Read an explicit group",
+            description = "Returns one explicit group owned by a dataverse.")
     public Response getGroupByOwnerAndAliasInOwner(@Context ContainerRequestContext crc,
+                                                   @Parameter(description = "Dataverse alias, id, or persistent identifier.", required = true)
                                                    @PathParam("identifier") String dvIdtf,
+                                                   @Parameter(description = "Group alias within the dataverse.", required = true)
                                                    @PathParam("aliasInOwner") String grpAliasInOwner) {
         return response(req -> ok(json(findExplicitGroupOrDie(findDataverseOrDie(dvIdtf),
                 req,
@@ -1454,7 +1712,12 @@ public Response getGroupByOwnerAndAliasInOwner(@Context ContainerRequestContext
     @GET
     @AuthRequired
     @Path("{identifier}/guestbookResponses/")
-    public Response getGuestbookResponsesByDataverse(@Context ContainerRequestContext crc, @PathParam("identifier") String dvIdtf,
+    @Operation(summary = "Export guestbook responses for a dataverse",
+            description = "Streams guestbook response data for datasets in a dataverse as CSV.")
+    public Response getGuestbookResponsesByDataverse(@Context ContainerRequestContext crc,
+            @Parameter(description = "Dataverse alias, id, or persistent identifier.", required = true)
+            @PathParam("identifier") String dvIdtf,
+            @Parameter(description = "Guestbook database id used to filter responses.")
             @QueryParam("guestbookId") Long gbId, @Context HttpServletResponse response) {
 
         Dataverse dv;
@@ -1496,8 +1759,14 @@ public void write(OutputStream os) throws IOException,
     @PUT
     @AuthRequired
     @Path("{identifier}/groups/{aliasInOwner}")
-    public Response updateGroup(@Context ContainerRequestContext crc, ExplicitGroupDTO groupDto,
+    @Operation(summary = "Revise an explicit group",
+            description = "Updates an explicit group owned by a dataverse.")
+    public Response updateGroup(@Context ContainerRequestContext crc,
+            @RequestBody(description = "Explicit group definition to apply.")
+            ExplicitGroupDTO groupDto,
+            @Parameter(description = "Dataverse alias, id, or persistent identifier.", required = true)
             @PathParam("identifier") String dvIdtf,
+            @Parameter(description = "Group alias within the dataverse.", required = true)
             @PathParam("aliasInOwner") String grpAliasInOwner) {
         return response(req -> ok(json(execCommand(
                 new UpdateExplicitGroupCommand(req,
@@ -1507,9 +1776,13 @@ public Response updateGroup(@Context ContainerRequestContext crc, ExplicitGroupD
     @PUT
     @AuthRequired
     @Path("{identifier}/defaultContributorRole/{roleAlias}")
+    @Operation(summary = "Assign a default contributor role",
+            description = "Sets the default contributor role used for datasets created in a dataverse.")
     public Response updateDefaultContributorRole(
             @Context ContainerRequestContext crc,
+            @Parameter(description = "Dataverse alias, id, or persistent identifier.", required = true)
             @PathParam("identifier") String dvIdtf,
+            @Parameter(description = "Role alias to use as the default contributor role, or none.", required = true)
             @PathParam("roleAlias") String roleAlias) {
 
         DataverseRole defaultRole;
@@ -1555,8 +1828,11 @@ public Response updateDefaultContributorRole(
     @GET
     @AuthRequired
     @Path("{identifier}/defaultContributorRole")
+    @Operation(summary = "Read the default contributor role",
+            description = "Returns the default contributor role configured for a dataverse.")
     public Response getDefaultContributorRole(
             @Context ContainerRequestContext crc,
+            @Parameter(description = "Dataverse alias, id, or persistent identifier.", required = true)
             @PathParam("identifier") String dvIdtf) {
 
         return response(req -> ok(
@@ -1570,8 +1846,12 @@ public Response getDefaultContributorRole(
     @DELETE
     @AuthRequired
     @Path("{identifier}/groups/{aliasInOwner}")
+    @Operation(summary = "Remove an explicit group",
+            description = "Deletes an explicit group owned by a dataverse.")
     public Response deleteGroup(@Context ContainerRequestContext crc,
+                                @Parameter(description = "Dataverse alias, id, or persistent identifier.", required = true)
                                 @PathParam("identifier") String dvIdtf,
+                                @Parameter(description = "Group alias within the dataverse.", required = true)
                                 @PathParam("aliasInOwner") String grpAliasInOwner) {
         return response(req -> {
             execCommand(new DeleteExplicitGroupCommand(req,
@@ -1584,9 +1864,14 @@ public Response deleteGroup(@Context ContainerRequestContext crc,
     @AuthRequired
     @Path("{identifier}/groups/{aliasInOwner}/roleAssignees")
     @Consumes("application/json")
+    @Operation(summary = "Append role assignees to an explicit group",
+            description = "Adds multiple role assignee identifiers to an explicit group.")
     public Response addRoleAssingees(@Context ContainerRequestContext crc,
+                                     @RequestBody(description = "JSON array of role assignee identifiers to add.")
                                      List<String> roleAssingeeIdentifiers,
+                                     @Parameter(description = "Dataverse alias, id, or persistent identifier.", required = true)
                                      @PathParam("identifier") String dvIdtf,
+                                     @Parameter(description = "Group alias within the dataverse.", required = true)
                                      @PathParam("aliasInOwner") String grpAliasInOwner) {
         return response(req -> ok(
                 json(
@@ -1599,9 +1884,14 @@ public Response addRoleAssingees(@Context ContainerRequestContext crc,
     @PUT
     @AuthRequired
     @Path("{identifier}/groups/{aliasInOwner}/roleAssignees/{roleAssigneeIdentifier: .*}")
+    @Operation(summary = "Append one role assignee to an explicit group",
+            description = "Adds one role assignee identifier to an explicit group.")
     public Response addRoleAssingee(@Context ContainerRequestContext crc,
+                                    @Parameter(description = "Dataverse alias, id, or persistent identifier.", required = true)
                                     @PathParam("identifier") String dvIdtf,
+                                    @Parameter(description = "Group alias within the dataverse.", required = true)
                                     @PathParam("aliasInOwner") String grpAliasInOwner,
+                                    @Parameter(description = "Role assignee identifier to add to the group.", required = true)
                                     @PathParam("roleAssigneeIdentifier") String roleAssigneeIdentifier) {
         return addRoleAssingees(crc, Collections.singletonList(roleAssigneeIdentifier), dvIdtf, grpAliasInOwner);
     }
@@ -1609,9 +1899,14 @@ public Response addRoleAssingee(@Context ContainerRequestContext crc,
     @DELETE
     @AuthRequired
     @Path("{identifier}/groups/{aliasInOwner}/roleAssignees/{roleAssigneeIdentifier: .*}")
+    @Operation(summary = "Remove one role assignee from an explicit group",
+            description = "Removes one role assignee identifier from an explicit group.")
     public Response deleteRoleAssingee(@Context ContainerRequestContext crc,
+                                       @Parameter(description = "Dataverse alias, id, or persistent identifier.", required = true)
                                        @PathParam("identifier") String dvIdtf,
+                                       @Parameter(description = "Group alias within the dataverse.", required = true)
                                        @PathParam("aliasInOwner") String grpAliasInOwner,
+                                       @Parameter(description = "Role assignee identifier to remove from the group.", required = true)
                                        @PathParam("roleAssigneeIdentifier") String roleAssigneeIdentifier) {
         return response(req -> ok(json(execCommand(
                 new RemoveRoleAssigneesFromExplicitGroupCommand(req,
@@ -1630,7 +1925,11 @@ private ExplicitGroup findExplicitGroupOrDie(DvObject dv, DataverseRequest req,
     @GET
     @AuthRequired
     @Path("{identifier}/links")
-    public Response listLinks(@Context ContainerRequestContext crc, @PathParam("identifier") String dvIdtf) {
+    @Operation(summary = "Read dataverse links",
+            description = "Returns dataverses and datasets linked from a dataverse and dataverses linking to it.")
+    public Response listLinks(@Context ContainerRequestContext crc,
+            @Parameter(description = "Dataverse alias, id, or persistent identifier.", required = true)
+            @PathParam("identifier") String dvIdtf) {
         try {
             User u = getRequestUser(crc);
             Dataverse dv = findDataverseOrDie(dvIdtf);
@@ -1681,7 +1980,15 @@ public Response listLinks(@Context ContainerRequestContext crc, @PathParam("iden
     @POST
     @AuthRequired
     @Path("{id}/move/{targetDataverseAlias}")
-    public Response moveDataverse(@Context ContainerRequestContext crc, @PathParam("id") String id, @PathParam("targetDataverseAlias") String targetDataverseAlias, @QueryParam("forceMove") Boolean force) {
+    @Operation(summary = "Move a dataverse",
+            description = "Moves a dataverse collection to a different parent dataverse.")
+    public Response moveDataverse(@Context ContainerRequestContext crc,
+            @Parameter(description = "Dataverse alias, id, or persistent identifier to move.", required = true)
+            @PathParam("id") String id,
+            @Parameter(description = "Alias of the target parent dataverse.", required = true)
+            @PathParam("targetDataverseAlias") String targetDataverseAlias,
+            @Parameter(description = "Whether to force the move when warnings would otherwise block it.")
+            @QueryParam("forceMove") Boolean force) {
         try {
             User u = getRequestUser(crc);
             Dataverse dv = findDataverseOrDie(id);
@@ -1701,7 +2008,13 @@ public Response moveDataverse(@Context ContainerRequestContext crc, @PathParam("
     @PUT
     @AuthRequired
     @Path("{linkedDataverseAlias}/link/{linkingDataverseAlias}")
-    public Response linkDataverse(@Context ContainerRequestContext crc, @PathParam("linkedDataverseAlias") String linkedDataverseAlias, @PathParam("linkingDataverseAlias") String linkingDataverseAlias) {
+    @Operation(summary = "Link one dataverse from another",
+            description = "Creates a link from one dataverse to another dataverse.")
+    public Response linkDataverse(@Context ContainerRequestContext crc,
+            @Parameter(description = "Alias of the dataverse being linked.", required = true)
+            @PathParam("linkedDataverseAlias") String linkedDataverseAlias,
+            @Parameter(description = "Alias of the dataverse that will contain the link.", required = true)
+            @PathParam("linkingDataverseAlias") String linkingDataverseAlias) {
         try {
             User u = getRequestUser(crc);
             Dataverse linked = findDataverseOrDie(linkedDataverseAlias);
@@ -1725,7 +2038,17 @@ public Response linkDataverse(@Context ContainerRequestContext crc, @PathParam("
     @AuthRequired
     @Produces(MediaType.APPLICATION_JSON)
     @Path("{identifier}/{type}/linkingDataverses")
-    public Response getLinkingDataverseList(@Context ContainerRequestContext crc, @PathParam("identifier") String dvIdtf, @QueryParam("searchTerm") String searchTerm, @QueryParam("alreadyLinking") boolean alreadyLinking, @PathParam("type") String type) {
+    @Operation(summary = "Search dataverses for linking",
+            description = "Lists dataverses that can be linked to the selected dataverse object, optionally filtered by search text and existing link status.")
+    public Response getLinkingDataverseList(@Context ContainerRequestContext crc,
+            @Parameter(description = "Dataverse object id or persistent identifier.", required = true)
+            @PathParam("identifier") String dvIdtf,
+            @Parameter(description = "Search text used to filter dataverses.")
+            @QueryParam("searchTerm") String searchTerm,
+            @Parameter(description = "Whether to return dataverses already linking to the object.")
+            @QueryParam("alreadyLinking") boolean alreadyLinking,
+            @Parameter(description = "Dataverse object type used to resolve the identifier.", required = true)
+            @PathParam("type") String type) {
 
         try {
 
@@ -1754,7 +2077,11 @@ public Response getLinkingDataverseList(@Context ContainerRequestContext crc, @P
     @GET
     @AuthRequired
     @Path("{identifier}/userPermissions")
-    public Response getUserPermissionsOnDataverse(@Context ContainerRequestContext crc, @PathParam("identifier") String dvIdtf) {
+    @Operation(summary = "Read user permissions on a dataverse",
+            description = "Returns booleans for the requesting user's key dataverse permissions.")
+    public Response getUserPermissionsOnDataverse(@Context ContainerRequestContext crc,
+            @Parameter(description = "Dataverse alias, id, or persistent identifier.", required = true)
+            @PathParam("identifier") String dvIdtf) {
         Dataverse dataverse;
         try {
             dataverse = findDataverseOrDie(dvIdtf);
@@ -1777,13 +2104,22 @@ public Response getUserPermissionsOnDataverse(@Context ContainerRequestContext c
     @AuthRequired
     @Consumes(MediaType.MULTIPART_FORM_DATA)
     @Path("{identifier}/featuredItems")
+    @Operation(summary = "Provision a dataverse featured item",
+            description = "Creates a featured item with text, optional linked object, display order, and optional image.")
     public Response createFeaturedItem(@Context ContainerRequestContext crc,
+                                       @Parameter(description = "Dataverse alias, id, or persistent identifier.", required = true)
                                        @PathParam("identifier") String dvIdtf,
+                                       @Parameter(description = "Featured item type used to resolve an optional linked object.")
                                        @FormDataParam("type") String type,
+                                       @Parameter(description = "Identifier of the optional dataverse object linked by this featured item.")
                                        @FormDataParam("dvObjectIdentifier") String dvObjectIdtf,
+                                       @Parameter(description = "Featured item text or link content.")
                                        @FormDataParam("content") String content,
+                                       @Parameter(description = "Display order for the featured item.")
                                        @FormDataParam("displayOrder") int displayOrder,
+                                       @Parameter(description = "Featured item image file.")
                                        @FormDataParam("file") InputStream imageFileInputStream,
+                                       @Parameter(description = "Uploaded image file metadata.")
                                        @FormDataParam("file") FormDataContentDisposition contentDispositionHeader) {
         Dataverse dataverse;
         DvObject dvObject = null;
@@ -1811,7 +2147,11 @@ public Response createFeaturedItem(@Context ContainerRequestContext crc,
     @GET
     @AuthRequired
     @Path("{identifier}/featuredItems")
-    public Response listFeaturedItems(@Context ContainerRequestContext crc, @PathParam("identifier") String dvIdtf) {
+    @Operation(summary = "Read dataverse featured items",
+            description = "Lists featured items configured on a dataverse.")
+    public Response listFeaturedItems(@Context ContainerRequestContext crc,
+            @Parameter(description = "Dataverse alias, id, or persistent identifier.", required = true)
+            @PathParam("identifier") String dvIdtf) {
         try {
             Dataverse dataverse = findDataverseOrDie(dvIdtf);
             List<DataverseFeaturedItem> featuredItems = execCommand(new ListDataverseFeaturedItemsCommand(createDataverseRequest(getRequestUser(crc)), dataverse));
@@ -1825,16 +2165,27 @@ public Response listFeaturedItems(@Context ContainerRequestContext crc, @PathPar
     @AuthRequired
     @Consumes(MediaType.MULTIPART_FORM_DATA)
     @Path("{dataverseId}/featuredItems")
+    @Operation(summary = "Replace dataverse featured items",
+            description = "Creates, updates, reorders, and removes featured items for a dataverse from multipart form lists.")
     public Response updateFeaturedItems(
             @Context ContainerRequestContext crc,
+            @Parameter(description = "Dataverse alias, id, or persistent identifier.", required = true)
             @PathParam("dataverseId") String dvIdtf,
+            @Parameter(description = "Featured item ids; use 0 for new items.")
             @FormDataParam("id") List<Long> ids,
+            @Parameter(description = "Featured item text or link content values.")
             @FormDataParam("content") List<String> contents,
+            @Parameter(description = "Featured item type values.")
             @FormDataParam("type") List<String> types,
+            @Parameter(description = "Optional linked dataverse object identifiers.")
             @FormDataParam("dvObjectIdentifier") List<String> dvObjectIdtf,
+            @Parameter(description = "Display order values.")
             @FormDataParam("displayOrder") List<Integer> displayOrders,
+            @Parameter(description = "Flags indicating whether to keep each existing image.")
             @FormDataParam("keepFile") List<Boolean> keepFiles,
+            @Parameter(description = "File names used to match uploaded images to featured items.")
             @FormDataParam("fileName") List<String> fileNames,
+            @Parameter(description = "Uploaded image file parts.")
             @FormDataParam("file") List<FormDataBodyPart> files) {
         try {
             if (ids == null || contents == null || displayOrders == null || keepFiles == null || fileNames == null) {
@@ -1909,7 +2260,11 @@ public Response updateFeaturedItems(
     @DELETE
     @AuthRequired
     @Path("{identifier}/featuredItems")
-    public Response deleteFeaturedItems(@Context ContainerRequestContext crc, @PathParam("identifier") String dvIdtf) {
+    @Operation(summary = "Clear dataverse featured items",
+            description = "Removes all featured items from a dataverse.")
+    public Response deleteFeaturedItems(@Context ContainerRequestContext crc,
+            @Parameter(description = "Dataverse alias, id, or persistent identifier.", required = true)
+            @PathParam("identifier") String dvIdtf) {
         try {
             Dataverse dataverse = findDataverseOrDie(dvIdtf);
             execCommand(new UpdateDataverseFeaturedItemsCommand(createDataverseRequest(getRequestUser(crc)), dataverse, new ArrayList<>(), new ArrayMap<>()));
@@ -1922,7 +2277,11 @@ public Response deleteFeaturedItems(@Context ContainerRequestContext crc, @PathP
     @GET
     @AuthRequired
     @Path("{identifier}/templates")
-    public Response getTemplates(@Context ContainerRequestContext crc, @PathParam("identifier") String dvIdtf) {
+    @Operation(summary = "Read dataverse templates",
+            description = "Lists metadata templates available in a dataverse.")
+    public Response getTemplates(@Context ContainerRequestContext crc,
+            @Parameter(description = "Dataverse alias, id, or persistent identifier.", required = true)
+            @PathParam("identifier") String dvIdtf) {
         try {
             Dataverse dataverse = findDataverseOrDie(dvIdtf);
             return ok(jsonTemplates(execCommand(new ListDataverseTemplatesCommand(createDataverseRequest(getRequestUser(crc)), dataverse))));
@@ -1934,7 +2293,11 @@ public Response getTemplates(@Context ContainerRequestContext crc, @PathParam("i
     @GET
     @AuthRequired
     @Path("{id}/template/")
-    public Response getTemplate(@Context ContainerRequestContext crc, @PathParam("id") Long templateId) {
+    @Operation(summary = "Read a metadata template",
+            description = "Returns one metadata template by database id.")
+    public Response getTemplate(@Context ContainerRequestContext crc,
+            @Parameter(description = "Template database id.", required = true)
+            @PathParam("id") Long templateId) {
         try {
             Template template = templateService.find(templateId);
             if (template == null){
@@ -1949,7 +2312,13 @@ public Response getTemplate(@Context ContainerRequestContext crc, @PathParam("id
     @POST
     @AuthRequired
     @Path("{identifier}/templates")
-    public Response createTemplate(@Context ContainerRequestContext crc, String body, @PathParam("identifier") String dvIdtf) {
+    @Operation(summary = "Provision a metadata template",
+            description = "Creates a metadata template owned by a dataverse.")
+    public Response createTemplate(@Context ContainerRequestContext crc,
+            @RequestBody(description = "Template JSON containing template metadata fields and settings.")
+            String body,
+            @Parameter(description = "Dataverse alias, id, or persistent identifier.", required = true)
+            @PathParam("identifier") String dvIdtf) {
         try {
             Dataverse dataverse = findDataverseOrDie(dvIdtf);
             TemplateDTO newTemplateDTO;
@@ -1970,7 +2339,15 @@ public Response createTemplate(@Context ContainerRequestContext crc, String body
     @PUT
     @AuthRequired
     @Path("{templateId}/metadata")
-    public Response updateTemplateMetadata(@Context ContainerRequestContext crc, String body, @PathParam("templateId") Long templateId, @QueryParam("replace") boolean replaceData) {
+    @Operation(summary = "Revise metadata template fields",
+            description = "Updates a template name, field values, and field instructions.")
+    public Response updateTemplateMetadata(@Context ContainerRequestContext crc,
+            @RequestBody(description = "Template metadata JSON containing name, fields, and optional instructions.")
+            String body,
+            @Parameter(description = "Template database id.", required = true)
+            @PathParam("templateId") Long templateId,
+            @Parameter(description = "When true, replace matching field values instead of merging.")
+            @QueryParam("replace") boolean replaceData) {
         try {
             Template template = findTemplateOrDie(templateId);
             Dataverse dataverse = template.getDataverse();
@@ -2021,7 +2398,15 @@ public Response updateTemplateMetadata(@Context ContainerRequestContext crc, Str
     @PUT
     @AuthRequired
     @Path("{templateId}/licenseTerms")
-    public Response updateTemplateLicenseTerms(@Context ContainerRequestContext crc, LicenseUpdateRequest requestBody, @PathParam("templateId") Long templateId, @QueryParam("replace") boolean replaceData) {
+    @Operation(summary = "Revise metadata template license terms",
+            description = "Updates the license or custom terms configured on a metadata template.")
+    public Response updateTemplateLicenseTerms(@Context ContainerRequestContext crc,
+            @RequestBody(description = "License update request containing a license name, URI, or custom terms.")
+            LicenseUpdateRequest requestBody,
+            @Parameter(description = "Template database id.", required = true)
+            @PathParam("templateId") Long templateId,
+            @Parameter(description = "Unused replace flag accepted by the endpoint.")
+            @QueryParam("replace") boolean replaceData) {
         try {
             Template template = findTemplateOrDie(templateId);
             Dataverse dataverse = template.getDataverse();
@@ -2051,7 +2436,13 @@ public Response updateTemplateLicenseTerms(@Context ContainerRequestContext crc,
     @PUT
     @AuthRequired
     @Path("{templateId}/access")
-    public Response updateTemplateTermsOfAccess(@Context ContainerRequestContext crc, String jsonBody, @PathParam("templateId") Long templateId) {
+    @Operation(summary = "Revise metadata template terms of access",
+            description = "Updates terms of use and access settings on a metadata template.")
+    public Response updateTemplateTermsOfAccess(@Context ContainerRequestContext crc,
+            @RequestBody(description = "JSON terms-of-access payload for the metadata template.")
+            String jsonBody,
+            @Parameter(description = "Template database id.", required = true)
+            @PathParam("templateId") Long templateId) {
         try {
 
             boolean publicInstall = settingsSvc.isTrueForKey(SettingsServiceBean.Key.PublicInstall, false);
@@ -2082,8 +2473,12 @@ public Response updateTemplateTermsOfAccess(@Context ContainerRequestContext crc
     @POST
     @AuthRequired
     @Path("{identifier}/template/default/{templateId}")
+    @Operation(summary = "Assign the default metadata template",
+            description = "Sets the default metadata template for a dataverse.")
     public Response setDefaultTemplate(@Context ContainerRequestContext crc,
+            @Parameter(description = "Dataverse alias, id, or persistent identifier.", required = true)
             @PathParam("identifier") String dvId,
+            @Parameter(description = "Template database id.", required = true)
             @PathParam("templateId") Long templateId) {
 
         try {
@@ -2105,7 +2500,10 @@ public Response setDefaultTemplate(@Context ContainerRequestContext crc,
     @DELETE
     @AuthRequired
     @Path("{identifier}/template/default")
+    @Operation(summary = "Clear the default metadata template",
+            description = "Removes the default metadata template setting from a dataverse.")
     public Response removeDefaultTemplate(@Context ContainerRequestContext crc,
+            @Parameter(description = "Dataverse alias, id, or persistent identifier.", required = true)
             @PathParam("identifier") String dvId) {
         try {
             Dataverse dataverse = findDataverseOrDie(dvId);
@@ -2121,7 +2519,11 @@ public Response removeDefaultTemplate(@Context ContainerRequestContext crc,
     @GET
     @AuthRequired
     @Path("{identifier}/allowedMetadataLanguages")
-    public Response getMetadataLanguage(@Context ContainerRequestContext crc, @PathParam("identifier") String dvIdtf) {
+    @Operation(summary = "Read allowed metadata language",
+            description = "Returns the metadata language configured for a dataverse.")
+    public Response getMetadataLanguage(@Context ContainerRequestContext crc,
+            @Parameter(description = "Dataverse alias, id, or persistent identifier.", required = true)
+            @PathParam("identifier") String dvIdtf) {
         return response(req -> {
             Dataverse dataverse = findDataverseOrDie(dvIdtf);
             return ok(jsonLanguage(execCommand(
@@ -2132,7 +2534,13 @@ public Response getMetadataLanguage(@Context ContainerRequestContext crc, @PathP
     @PUT
     @AuthRequired
     @Path("{identifier}/allowedMetadataLanguages/{metadataLanguage}")
-    public Response setMetadataLanguage(@Context ContainerRequestContext crc, @PathParam("identifier") String dvIdtf, @PathParam("metadataLanguage") String lang) {
+    @Operation(summary = "Assign allowed metadata language",
+            description = "Sets the metadata language configured for a dataverse.")
+    public Response setMetadataLanguage(@Context ContainerRequestContext crc,
+            @Parameter(description = "Dataverse alias, id, or persistent identifier.", required = true)
+            @PathParam("identifier") String dvIdtf,
+            @Parameter(description = "Metadata language code to assign.", required = true)
+            @PathParam("metadataLanguage") String lang) {
         return response(req -> {
             Map<String, String> langMap = settingsService.getBaseMetadataLanguageMap(null, true);
             if (langMap.isEmpty()) {
@@ -2149,7 +2557,11 @@ public Response setMetadataLanguage(@Context ContainerRequestContext crc, @PathP
     @Path("{id}/template")
     @AuthRequired
     @DELETE
-    public Response deleteTemplate(@Context ContainerRequestContext crc, @PathParam("id") long id) {
+    @Operation(summary = "Remove a metadata template",
+            description = "Deletes a metadata template and clears default-template references that point to it.")
+    public Response deleteTemplate(@Context ContainerRequestContext crc,
+            @Parameter(description = "Template database id.", required = true)
+            @PathParam("id") long id) {
 
         Template doomed = templateService.find(id);
         if (doomed == null) {
@@ -2171,7 +2583,10 @@ public Response deleteTemplate(@Context ContainerRequestContext crc, @PathParam(
     @AuthRequired
     @Path("{identifier}/assignments/history")
     @Produces({ MediaType.APPLICATION_JSON, "text/csv" })
+    @Operation(summary = "Read dataverse role assignment history",
+            description = "Returns dataverse role assignment history as JSON or CSV.")
     public Response getRoleAssignmentHistory(@Context ContainerRequestContext crc,
+            @Parameter(description = "Dataverse alias, id, or persistent identifier.", required = true)
             @PathParam("identifier") String id,
             @Context HttpHeaders headers) {
         return response(req -> {
@@ -2192,7 +2607,12 @@ public Response getRoleAssignmentHistory(@Context ContainerRequestContext crc,
     @GET
     @AuthRequired
     @Path("{identifier}/storageDriver")
-    public Response getStorageDriver(@Context ContainerRequestContext crc, @PathParam("identifier") String id,
+    @Operation(summary = "Read dataverse storage driver",
+            description = "Returns the storage driver configured for a dataverse, optionally resolving the effective inherited driver.")
+    public Response getStorageDriver(@Context ContainerRequestContext crc,
+                                     @Parameter(description = "Dataverse alias, id, or persistent identifier.", required = true)
+                                     @PathParam("identifier") String id,
+                                     @Parameter(description = "Whether to resolve the effective inherited storage driver.")
                                      @QueryParam("getEffective") Boolean getEffective) throws WrappedResponse {
 
         Dataverse dataverse = findDataverseOrDie(id);
@@ -2206,8 +2626,13 @@ public Response getStorageDriver(@Context ContainerRequestContext crc, @PathPara
     @PUT
     @AuthRequired
     @Path("{identifier}/storageDriver")
+    @Operation(summary = "Assign dataverse storage driver",
+            description = "Sets the storage driver for a dataverse by driver label.")
     public Response setStorageDriver(@Context ContainerRequestContext crc, 
-                                     @PathParam("identifier") String id, String label) throws WrappedResponse {
+                                     @Parameter(description = "Dataverse alias, id, or persistent identifier.", required = true)
+                                     @PathParam("identifier") String id,
+                                     @RequestBody(description = "Storage driver label to assign.")
+                                     String label) throws WrappedResponse {
         Dataverse dataverse = findDataverseOrDie(id);
 
         try {
@@ -2231,7 +2656,11 @@ public Response setStorageDriver(@Context ContainerRequestContext crc,
     @DELETE
     @AuthRequired
     @Path("{identifier}/storageDriver")
-    public Response resetStorageDriver(@Context ContainerRequestContext crc, @PathParam("identifier") String id) throws WrappedResponse {
+    @Operation(summary = "Reset dataverse storage driver",
+            description = "Clears the explicit storage driver setting so the dataverse uses the default driver.")
+    public Response resetStorageDriver(@Context ContainerRequestContext crc,
+            @Parameter(description = "Dataverse alias, id, or persistent identifier.", required = true)
+            @PathParam("identifier") String id) throws WrappedResponse {
         
         Dataverse dataverse = findDataverseOrDie(id);
         try {
@@ -2250,7 +2679,11 @@ public Response resetStorageDriver(@Context ContainerRequestContext crc, @PathPa
     @GET
     @AuthRequired
     @Path("{identifier}/allowedStorageDrivers")
-    public Response listStorageDrivers(@Context ContainerRequestContext crc, @PathParam("identifier") String id) throws WrappedResponse {
+    @Operation(summary = "Read allowed storage drivers",
+            description = "Returns storage drivers available for the selected dataverse.")
+    public Response listStorageDrivers(@Context ContainerRequestContext crc,
+            @Parameter(description = "Dataverse alias, id, or persistent identifier.", required = true)
+            @PathParam("identifier") String id) throws WrappedResponse {
         
         Dataverse dv = findDataverseOrDie(id);
 
@@ -2269,4 +2702,4 @@ public Response listStorageDrivers(@Context ContainerRequestContext crc, @PathPa
         } 
     }
 
-}
\ No newline at end of file
+}
diff --git a/src/main/java/edu/harvard/iq/dataverse/api/EditDDI.java b/src/main/java/edu/harvard/iq/dataverse/api/EditDDI.java
index 1755e66823a..e25d9f34d96 100644
--- a/src/main/java/edu/harvard/iq/dataverse/api/EditDDI.java
+++ b/src/main/java/edu/harvard/iq/dataverse/api/EditDDI.java
@@ -40,6 +40,11 @@
 import jakarta.ws.rs.PUT;
 import jakarta.ws.rs.Consumes;
 import jakarta.ws.rs.PathParam;
+import org.eclipse.microprofile.openapi.annotations.Operation;
+import org.eclipse.microprofile.openapi.annotations.parameters.Parameter;
+import org.eclipse.microprofile.openapi.annotations.parameters.RequestBody;
+import org.eclipse.microprofile.openapi.annotations.security.SecurityRequirement;
+import org.eclipse.microprofile.openapi.annotations.tags.Tag;
 import javax.xml.stream.XMLStreamException;
 import javax.xml.stream.XMLInputFactory;
 import javax.xml.stream.XMLStreamReader;
@@ -58,6 +63,7 @@
 
 @Stateless
 @Path("edit")
+@Tag(name = "Files", description = "Data file metadata, upload, replacement, and editing operations.")
 public class EditDDI  extends AbstractApiBean {
     private static final Logger logger = Logger.getLogger(Access.class.getCanonicalName());
 
@@ -93,7 +99,14 @@ public class EditDDI  extends AbstractApiBean {
     @AuthRequired
     @Path("{fileId}")
     @Consumes("application/xml")
-    public Response edit(@Context ContainerRequestContext crc, InputStream body, @PathParam("fileId") String fileId) {
+    @SecurityRequirement(name = "DataverseApiKey")
+    @Operation(summary = "Updates tabular file variable metadata",
+            description = "Parses DDI XML for a tabular data file and updates variable metadata on the draft dataset version, creating a draft when needed.")
+    public Response edit(@Context ContainerRequestContext crc,
+            @RequestBody(description = "DDI XML containing variable metadata and variable group updates for the tabular file.")
+            InputStream body,
+            @Parameter(description = "Data file id whose variable metadata is updated.", required = true)
+            @PathParam("fileId") String fileId) {
         DataFile dataFile = null;
         try {
             dataFile = findDataFileOrDie(fileId);
diff --git a/src/main/java/edu/harvard/iq/dataverse/api/ExternalTools.java b/src/main/java/edu/harvard/iq/dataverse/api/ExternalTools.java
index 1feac1141bb..9d094360681 100644
--- a/src/main/java/edu/harvard/iq/dataverse/api/ExternalTools.java
+++ b/src/main/java/edu/harvard/iq/dataverse/api/ExternalTools.java
@@ -13,13 +13,20 @@
 import jakarta.ws.rs.PathParam;
 import jakarta.ws.rs.core.Response;
 import static jakarta.ws.rs.core.Response.Status.BAD_REQUEST;
+import org.eclipse.microprofile.openapi.annotations.Operation;
+import org.eclipse.microprofile.openapi.annotations.parameters.Parameter;
+import org.eclipse.microprofile.openapi.annotations.parameters.RequestBody;
+import org.eclipse.microprofile.openapi.annotations.tags.Tag;
 
 @Path("admin/externalTools")
+@Tag(name = "External Tools", description = "External tool registration and lookup operations.")
 public class ExternalTools extends AbstractApiBean {
 
     private static final Logger logger = Logger.getLogger(ExternalTools.class.getCanonicalName());
 
     @GET
+    @Operation(summary = "Lists external tools",
+            description = "Returns all registered external tools as JSON.")
     public Response getExternalTools() {
         JsonArrayBuilder jab = Json.createArrayBuilder();
         externalToolService.findAll().forEach((externalTool) -> {
@@ -30,7 +37,11 @@ public Response getExternalTools() {
 
     @GET
     @Path("{id}")
-    public Response getExternalTool(@PathParam("id") long externalToolIdFromUser) {
+    @Operation(summary = "Returns an external tool",
+            description = "Returns the registered external tool with the specified numeric id.")
+    public Response getExternalTool(
+            @Parameter(description = "Numeric id of the external tool to return.", required = true)
+            @PathParam("id") long externalToolIdFromUser) {
         ExternalTool externalTool = externalToolService.findById(externalToolIdFromUser);
         if (externalTool != null) {
             return ok(externalTool.toJson());
@@ -40,7 +51,11 @@ public Response getExternalTool(@PathParam("id") long externalToolIdFromUser) {
     }
 
     @POST
-    public Response addExternalTool(String manifest) {
+    @Operation(summary = "Registers an external tool",
+            description = "Parses an external tool manifest, saves the tool definition, and returns the saved tool as JSON.")
+    public Response addExternalTool(
+            @RequestBody(description = "External tool manifest JSON to parse and register.")
+            String manifest) {
         try {
             ExternalTool externalTool = ExternalToolServiceBean.parseAddExternalToolManifest(manifest);
             ExternalTool saved = externalToolService.save(externalTool);
@@ -55,7 +70,11 @@ public Response addExternalTool(String manifest) {
 
     @DELETE
     @Path("{id}")
-    public Response deleteExternalTool(@PathParam("id") long externalToolIdFromUser) {
+    @Operation(summary = "Deletes an external tool",
+            description = "Deletes the registered external tool with the specified numeric id.")
+    public Response deleteExternalTool(
+            @Parameter(description = "Numeric id of the external tool to delete.", required = true)
+            @PathParam("id") long externalToolIdFromUser) {
         boolean deleted = externalToolService.delete(externalToolIdFromUser);
         if (deleted) {
             return ok("Deleted external tool with id of " + externalToolIdFromUser);
diff --git a/src/main/java/edu/harvard/iq/dataverse/api/ExternalToolsApi.java b/src/main/java/edu/harvard/iq/dataverse/api/ExternalToolsApi.java
index 6185e91b889..20bfe378fc2 100644
--- a/src/main/java/edu/harvard/iq/dataverse/api/ExternalToolsApi.java
+++ b/src/main/java/edu/harvard/iq/dataverse/api/ExternalToolsApi.java
@@ -11,14 +11,22 @@
 import jakarta.ws.rs.container.ContainerRequestContext;
 import jakarta.ws.rs.core.Context;
 import jakarta.ws.rs.core.Response;
+import org.eclipse.microprofile.openapi.annotations.Operation;
+import org.eclipse.microprofile.openapi.annotations.parameters.Parameter;
+import org.eclipse.microprofile.openapi.annotations.parameters.RequestBody;
+import org.eclipse.microprofile.openapi.annotations.security.SecurityRequirement;
+import org.eclipse.microprofile.openapi.annotations.tags.Tag;
 
 @Path("externalTools")
+@Tag(name = "External Tools", description = "External tool registration and lookup operations.")
 public class ExternalToolsApi extends AbstractApiBean {
 
     @Inject
     ExternalTools externalTools;
 
     @GET
+    @Operation(summary = "Lists external tools",
+            description = "Returns all registered external tools.")
     public Response getExternalTools() {
         //ToDo - allow filtering by scope, tool type, file content type, etc?
         return externalTools.getExternalTools();
@@ -26,13 +34,22 @@ public Response getExternalTools() {
 
     @GET
     @Path("{id}")
-    public Response getExternalTool(@PathParam("id") long externalToolIdFromUser) {
+    @Operation(summary = "Returns an external tool",
+            description = "Returns the registered external tool with the specified numeric id.")
+    public Response getExternalTool(
+            @Parameter(description = "Numeric id of the external tool to return.", required = true)
+            @PathParam("id") long externalToolIdFromUser) {
         return externalTools.getExternalTool(externalToolIdFromUser);
     }
 
     @POST
     @AuthRequired
-    public Response addExternalTool(@Context ContainerRequestContext crc, String manifest) {
+    @SecurityRequirement(name = "DataverseApiKey")
+    @Operation(summary = "Registers an external tool",
+            description = "Registers an external tool from its manifest when the authenticated user is a superuser.")
+    public Response addExternalTool(@Context ContainerRequestContext crc,
+            @RequestBody(description = "External tool manifest JSON to register.")
+            String manifest) {
         Response notAuthorized = authorize(crc);
         return notAuthorized == null ? externalTools.addExternalTool(manifest) : notAuthorized;
     }
@@ -40,7 +57,12 @@ public Response addExternalTool(@Context ContainerRequestContext crc, String man
     @DELETE
     @AuthRequired
     @Path("{id}")
-    public Response deleteExternalTool(@Context ContainerRequestContext crc, @PathParam("id") long externalToolIdFromUser) {
+    @SecurityRequirement(name = "DataverseApiKey")
+    @Operation(summary = "Deletes an external tool",
+            description = "Deletes the registered external tool with the specified numeric id when the authenticated user is a superuser.")
+    public Response deleteExternalTool(@Context ContainerRequestContext crc,
+            @Parameter(description = "Numeric id of the external tool to delete.", required = true)
+            @PathParam("id") long externalToolIdFromUser) {
         Response notAuthorized = authorize(crc);
         return notAuthorized == null ? externalTools.deleteExternalTool(externalToolIdFromUser) : notAuthorized;
     }
diff --git a/src/main/java/edu/harvard/iq/dataverse/api/FeedbackApi.java b/src/main/java/edu/harvard/iq/dataverse/api/FeedbackApi.java
index 56c5ca95ce6..9d180096228 100644
--- a/src/main/java/edu/harvard/iq/dataverse/api/FeedbackApi.java
+++ b/src/main/java/edu/harvard/iq/dataverse/api/FeedbackApi.java
@@ -19,8 +19,12 @@
 import jakarta.ws.rs.Path;
 import jakarta.ws.rs.core.Response;
 import jakarta.ws.rs.core.Response.Status;
+import org.eclipse.microprofile.openapi.annotations.Operation;
+import org.eclipse.microprofile.openapi.annotations.parameters.RequestBody;
+import org.eclipse.microprofile.openapi.annotations.tags.Tag;
 
 @Path("admin/feedback")
+@Tag(name = "Admin", description = "Administrative Dataverse operations.")
 public class FeedbackApi extends AbstractApiBean {
 
     @EJB MailServiceBean mailService;
@@ -35,9 +39,13 @@ public class FeedbackApi extends AbstractApiBean {
      * unauthenticated user (with access to the /admin api path) to send email from
      * anyone to any contacts in Dataverse. (It also does not do much to validate
      * user input (e.g. to strip potentially malicious html, etc.)!!!!
-     **/
+    **/
     @POST
-    public Response submitFeedback(JsonObject jsonObject) {
+    @Operation(summary = "Submits administrative feedback",
+            description = "Sends a feedback email to contacts for a target object or to the support address when no target is supplied.")
+    public Response submitFeedback(
+            @RequestBody(description = "Feedback JSON with subject, body, sender email, and an optional target object id.")
+            JsonObject jsonObject) {
         JsonNumber jsonNumber = jsonObject.getJsonNumber("targetId");
         DvObject feedbackTarget = null;
         if (jsonNumber != null) {
diff --git a/src/main/java/edu/harvard/iq/dataverse/api/Files.java b/src/main/java/edu/harvard/iq/dataverse/api/Files.java
index 0a1b19985a4..1af4e66fc8a 100644
--- a/src/main/java/edu/harvard/iq/dataverse/api/Files.java
+++ b/src/main/java/edu/harvard/iq/dataverse/api/Files.java
@@ -71,14 +71,17 @@
 import org.apache.commons.lang3.StringUtils;
 import org.eclipse.microprofile.openapi.annotations.Operation;
 import org.eclipse.microprofile.openapi.annotations.media.Content;
+import org.eclipse.microprofile.openapi.annotations.parameters.Parameter;
 import org.eclipse.microprofile.openapi.annotations.parameters.RequestBody;
 import org.eclipse.microprofile.openapi.annotations.responses.APIResponse;
+import org.eclipse.microprofile.openapi.annotations.security.SecurityRequirement;
 import org.eclipse.microprofile.openapi.annotations.tags.Tag;
 import org.glassfish.jersey.media.multipart.FormDataBodyPart;
 import org.glassfish.jersey.media.multipart.FormDataContentDisposition;
 import org.glassfish.jersey.media.multipart.FormDataParam;
 
 @Path("files")
+@Tag(name = "Files", description = "Manage data files, file metadata, file replacement, and file-specific utilities.")
 public class Files extends AbstractApiBean {
     
     @EJB
@@ -131,7 +134,14 @@ private void msgt(String m){
     @PUT
     @AuthRequired
     @Path("{id}/restrict")
-    public Response restrictFileInDataset(@Context ContainerRequestContext crc, @PathParam("id") String fileToRestrictId, String restrictStr) {
+    @Operation(summary = "Change file restriction status",
+            description = "Applies restricted or unrestricted status to a data file, with optional access-request and terms-of-access settings.")
+    @SecurityRequirement(name = "DataverseApiKey")
+    public Response restrictFileInDataset(@Context ContainerRequestContext crc,
+                                          @Parameter(description = "Data file id or persistent identifier.", required = true)
+                                          @PathParam("id") String fileToRestrictId,
+                                          @RequestBody(description = "Boolean value or JSON object containing restrict, enableAccessRequest, and termsOfAccess fields.")
+                                          String restrictStr) {
         //create request
         DataverseRequest dataverseRequest = null;
         //get the datafile
@@ -218,6 +228,7 @@ public Response restrictFileInDataset(@Context ContainerRequestContext crc, @Pat
     @Produces("application/json")
     @Operation(summary = "Replace a file on a dataset", 
                description = "Replace a file to a dataset")
+    @SecurityRequirement(name = "DataverseApiKey")
     @APIResponse(responseCode = "200",
                description = "File replaced successfully on the dataset")
     @Tag(name = "replaceFilesInDataset", 
@@ -225,10 +236,15 @@ public Response restrictFileInDataset(@Context ContainerRequestContext crc, @Pat
     @RequestBody(content = @Content(mediaType = MediaType.MULTIPART_FORM_DATA)) 
     public Response replaceFileInDataset(
                     @Context ContainerRequestContext crc,
+                    @Parameter(description = "Data file id or persistent identifier for the file being replaced.", required = true)
                     @PathParam("id") String fileIdOrPersistentId,
+                    @Parameter(description = "JSON metadata and replacement options for the uploaded file.")
                     @FormDataParam("jsonData") String jsonData,
+                    @Parameter(description = "Replacement file content.")
                     @FormDataParam("file") InputStream testFileInputStream,
+                    @Parameter(description = "Uploaded replacement file metadata.")
                     @FormDataParam("file") FormDataContentDisposition contentDispositionHeader,
+                    @Parameter(description = "Multipart body part for the replacement file.")
                     @FormDataParam("file") final FormDataBodyPart formDataBodyPart
                     ){
 
@@ -364,7 +380,12 @@ public Response replaceFileInDataset(
     @DELETE
     @AuthRequired
     @Path("{id}")
-    public Response deleteFileInDataset(@Context ContainerRequestContext crc, @PathParam("id") String fileIdOrPersistentId){
+    @Operation(summary = "Remove a file from its dataset",
+            description = "Removes a data file from the dataset draft and deletes the physical file when the file has never been released.")
+    @SecurityRequirement(name = "DataverseApiKey")
+    public Response deleteFileInDataset(@Context ContainerRequestContext crc,
+                                        @Parameter(description = "Data file id or persistent identifier.", required = true)
+                                        @PathParam("id") String fileIdOrPersistentId){
         // (1) Get the user from the API key and create request
         User authUser = getRequestUser(crc);
         DataverseRequest dvRequest = createDataverseRequest(authUser);
@@ -409,8 +430,16 @@ public Response deleteFileInDataset(@Context ContainerRequestContext crc, @PathP
     @POST
     @AuthRequired
     @Path("{id}/metadata")
-    public Response updateFileMetadata(@Context ContainerRequestContext crc, @FormDataParam("jsonData") String jsonData,
-                    @PathParam("id") String fileIdOrPersistentId, @QueryParam("sourceLastUpdateTime") String sourceLastUpdateTime) {
+    @Operation(summary = "Revise file metadata",
+            description = "Updates metadata for an existing data file using multipart JSON metadata.")
+    @SecurityRequirement(name = "DataverseApiKey")
+    public Response updateFileMetadata(@Context ContainerRequestContext crc,
+                    @Parameter(description = "JSON metadata update for the data file.")
+                    @FormDataParam("jsonData") String jsonData,
+                    @Parameter(description = "Data file id or persistent identifier.", required = true)
+                    @PathParam("id") String fileIdOrPersistentId,
+                    @Parameter(description = "Source last-update timestamp used by external integrations.")
+                    @QueryParam("sourceLastUpdateTime") String sourceLastUpdateTime) {
         
         FileMetadata upFmd = null;
         
@@ -794,7 +823,14 @@ public Response reingest(@Context ContainerRequestContext crc, @PathParam("id")
     @POST
     @AuthRequired
     @Path("{id}/redetect")
-    public Response redetectDatafile(@Context ContainerRequestContext crc, @PathParam("id") String id, @QueryParam("dryRun") boolean dryRun) {
+    @Operation(summary = "Re-evaluate file content type",
+            description = "Runs content-type detection for a non-tabular data file and optionally reports the result without saving it.")
+    @SecurityRequirement(name = "DataverseApiKey")
+    public Response redetectDatafile(@Context ContainerRequestContext crc,
+                                     @Parameter(description = "Data file id or persistent identifier.", required = true)
+                                     @PathParam("id") String id,
+                                     @Parameter(description = "When true, report the detected type without saving the change.")
+                                     @QueryParam("dryRun") boolean dryRun) {
         try {
             DataFile dataFileIn = findDataFileOrDie(id);
             // Ingested Files have mimetype = text/tab-separated-values
@@ -1005,8 +1041,18 @@ public Response getExternalToolUrl(@Context ContainerRequestContext crc, @PathPa
     @GET
     @AuthRequired
     @Path("{id}/metadata/{fmid}/toolparams/{tid}")
-    public Response getExternalToolFMParams(@Context ContainerRequestContext crc, @PathParam("tid") long externalToolId,
-            @PathParam("id") String fileId, @PathParam("fmid") long fmid, @QueryParam(value = "locale") String locale) {
+    @Operation(summary = "Resolve external tool parameters for file metadata",
+            description = "Reports the parameter payload and allowed API calls for an external tool working with a specific file metadata record.")
+    @SecurityRequirement(name = "DataverseApiKey")
+    public Response getExternalToolFMParams(@Context ContainerRequestContext crc,
+            @Parameter(description = "External tool database id.", required = true)
+            @PathParam("tid") long externalToolId,
+            @Parameter(description = "Data file id or persistent identifier.", required = true)
+            @PathParam("id") String fileId,
+            @Parameter(description = "File metadata database id.", required = true)
+            @PathParam("fmid") long fmid,
+            @Parameter(description = "Locale used when creating the external tool parameter payload.")
+            @QueryParam(value = "locale") String locale) {
         ExternalTool externalTool = externalToolService.findById(externalToolId);
         if(externalTool == null) {
             return error(BAD_REQUEST, "External tool not found.");
@@ -1030,6 +1076,8 @@ public Response getExternalToolFMParams(@Context ContainerRequestContext crc, @P
     
     @GET
     @Path("fixityAlgorithm")
+    @Operation(summary = "Show the configured file fixity algorithm",
+            description = "Reports the checksum algorithm configured for file fixity checks.")
     public Response getFixityAlgorithm() {
         return ok(systemConfig.getFileFixityChecksumAlgorithm().toString());
     }
@@ -1037,7 +1085,12 @@ public Response getFixityAlgorithm() {
     @GET
     @AuthRequired
     @Path("{id}/downloadCount")
-    public Response getFileDownloadCount(@Context ContainerRequestContext crc, @PathParam("id") String dataFileId) {
+    @Operation(summary = "Show file download count",
+            description = "Reports the recorded download count for a data file.")
+    @SecurityRequirement(name = "DataverseApiKey")
+    public Response getFileDownloadCount(@Context ContainerRequestContext crc,
+                                         @Parameter(description = "Data file id or persistent identifier.", required = true)
+                                         @PathParam("id") String dataFileId) {
         return response(req -> {
             DataFile dataFile = execCommand(new GetDataFileCommand(req, findDataFileOrDie(dataFileId)));
             return ok(guestbookResponseService.getDownloadCountByDataFileId(dataFile.getId()).toString());
@@ -1047,7 +1100,12 @@ public Response getFileDownloadCount(@Context ContainerRequestContext crc, @Path
     @GET
     @AuthRequired
     @Path("{id}/dataTables")
-    public Response getFileDataTables(@Context ContainerRequestContext crc, @PathParam("id") String dataFileId) {
+    @Operation(summary = "Show tabular data tables",
+            description = "Reports data table metadata associated with a tabular data file after checking file access when needed.")
+    @SecurityRequirement(name = "DataverseApiKey")
+    public Response getFileDataTables(@Context ContainerRequestContext crc,
+                                      @Parameter(description = "Data file id or persistent identifier.", required = true)
+                                      @PathParam("id") String dataFileId) {
         DataFile dataFile;
         try {
             dataFile = findDataFileOrDie(dataFileId);
@@ -1071,7 +1129,16 @@ public Response getFileDataTables(@Context ContainerRequestContext crc, @PathPar
     @AuthRequired
     @Path("{id}/metadata/categories")
     @Produces(MediaType.APPLICATION_JSON)
-    public Response setFileCategories(@Context ContainerRequestContext crc, @PathParam("id") String dataFileId, String jsonBody, @QueryParam("replace") boolean replaceData) {
+    @Operation(summary = "Apply category labels to file metadata",
+            description = "Adds or replaces category labels on the selected file metadata record.")
+    @SecurityRequirement(name = "DataverseApiKey")
+    public Response setFileCategories(@Context ContainerRequestContext crc,
+                                      @Parameter(description = "Data file id or persistent identifier.", required = true)
+                                      @PathParam("id") String dataFileId,
+                                      @RequestBody(description = "JSON object containing a categories array.")
+                                      String jsonBody,
+                                      @Parameter(description = "When true, replace existing categories before adding the supplied values.")
+                                      @QueryParam("replace") boolean replaceData) {
         return response(req -> {
             DataFile dataFile = execCommand(new GetDataFileCommand(req, findDataFileOrDie(dataFileId)));
             jakarta.json.JsonObject jsonObject;
@@ -1098,7 +1165,16 @@ public Response setFileCategories(@Context ContainerRequestContext crc, @PathPar
     @AuthRequired
     @Path("{id}/metadata/tabularTags")
     @Produces(MediaType.APPLICATION_JSON)
-    public Response setFileTabularTags(@Context ContainerRequestContext crc, @PathParam("id") String dataFileId, String jsonBody, @QueryParam("replace") boolean replaceData) {
+    @Operation(summary = "Apply tabular tags to a file",
+            description = "Adds or replaces tabular data tags on a tabular data file.")
+    @SecurityRequirement(name = "DataverseApiKey")
+    public Response setFileTabularTags(@Context ContainerRequestContext crc,
+                                       @Parameter(description = "Data file id or persistent identifier.", required = true)
+                                       @PathParam("id") String dataFileId,
+                                       @RequestBody(description = "JSON object containing a tabularTags array.")
+                                       String jsonBody,
+                                       @Parameter(description = "When true, replace existing tabular tags before adding the supplied values.")
+                                       @QueryParam("replace") boolean replaceData) {
         return response(req -> {
             DataFile dataFile = execCommand(new GetDataFileCommand(req, findDataFileOrDie(dataFileId)));
             if (!dataFile.isTabularData()) {
@@ -1130,7 +1206,12 @@ public Response setFileTabularTags(@Context ContainerRequestContext crc, @PathPa
     @GET
     @AuthRequired
     @Path("{id}/hasBeenDeleted")
-    public Response getHasBeenDeleted(@Context ContainerRequestContext crc, @PathParam("id") String dataFileId) {
+    @Operation(summary = "Check whether a file was deleted",
+            description = "Reports whether the selected data file has a deletion record.")
+    @SecurityRequirement(name = "DataverseApiKey")
+    public Response getHasBeenDeleted(@Context ContainerRequestContext crc,
+                                      @Parameter(description = "Data file id or persistent identifier.", required = true)
+                                      @PathParam("id") String dataFileId) {
         return response(req -> {
             DataFile dataFile = execCommand(new GetDataFileCommand(req, findDataFileOrDie(dataFileId)));
             return ok(dataFileServiceBean.hasBeenDeleted(dataFile));
@@ -1146,7 +1227,16 @@ public Response getHasBeenDeleted(@Context ContainerRequestContext crc, @PathPar
     @GET
     @AuthRequired
     @Path("{id}/versions/{dsVersionString}/citation")
-    public Response getFileCitationByVersion(@Context ContainerRequestContext crc, @PathParam("id") String fileIdOrPersistentId, @PathParam("dsVersionString") String versionNumber, @QueryParam("includeDeaccessioned") boolean includeDeaccessioned) {
+    @Operation(summary = "Format a citation for a file version",
+            description = "Reports the citation text for a data file in the requested dataset version.")
+    @SecurityRequirement(name = "DataverseApiKey")
+    public Response getFileCitationByVersion(@Context ContainerRequestContext crc,
+                                             @Parameter(description = "Data file id or persistent identifier.", required = true)
+                                             @PathParam("id") String fileIdOrPersistentId,
+                                             @Parameter(description = "Dataset version label, such as 1.0, :draft, or :latest-published.", required = true)
+                                             @PathParam("dsVersionString") String versionNumber,
+                                             @Parameter(description = "Whether deaccessioned dataset versions may be used.")
+                                             @QueryParam("includeDeaccessioned") boolean includeDeaccessioned) {
         try {
             DataverseRequest req = createDataverseRequest(getRequestUser(crc));
             final DataFile df = execCommand(new GetDataFileCommand(req, findDataFileOrDie(fileIdOrPersistentId)));
@@ -1173,9 +1263,15 @@ public Response getFileCitationByVersion(@Context ContainerRequestContext crc, @
     @AuthRequired
     @Path("{id}/versionDifferences")
     @Produces(MediaType.APPLICATION_JSON)
+    @Operation(summary = "Compare file versions",
+            description = "Reports metadata differences across versions for a data file.")
+    @SecurityRequirement(name = "DataverseApiKey")
     public Response getFileVersionsList(@Context ContainerRequestContext crc,
+                                        @Parameter(description = "Data file id or persistent identifier.", required = true)
                                         @PathParam("id") String fileIdOrPersistentId,
+                                        @Parameter(description = "Maximum number of version-difference records to return.")
                                         @QueryParam("limit") Integer limit,
+                                        @Parameter(description = "Number of version-difference records to skip before returning results.")
                                         @QueryParam("offset") Integer offset) {
         try {
             DataverseRequest req = createDataverseRequest(getRequestUser(crc));
diff --git a/src/main/java/edu/harvard/iq/dataverse/api/Groups.java b/src/main/java/edu/harvard/iq/dataverse/api/Groups.java
index ed996b8ecf9..55fb68857f3 100644
--- a/src/main/java/edu/harvard/iq/dataverse/api/Groups.java
+++ b/src/main/java/edu/harvard/iq/dataverse/api/Groups.java
@@ -30,6 +30,10 @@
 import jakarta.ws.rs.PUT;
 import jakarta.ws.rs.PathParam;
 import static org.apache.commons.lang3.StringUtils.isNumeric;
+import org.eclipse.microprofile.openapi.annotations.Operation;
+import org.eclipse.microprofile.openapi.annotations.parameters.Parameter;
+import org.eclipse.microprofile.openapi.annotations.parameters.RequestBody;
+import org.eclipse.microprofile.openapi.annotations.tags.Tag;
 
 /**
  *
@@ -37,6 +41,7 @@
  */
 @Path("admin/groups")
 @Stateless
+@Tag(name = "Admin", description = "Administrative Dataverse operations.")
 public class Groups extends AbstractApiBean {
     private static final Logger logger = Logger.getLogger(Groups.class.getName());
 
@@ -62,7 +67,11 @@ void postConstruct() {
      */
     @POST
     @Path("ip")
-    public Response postIpGroup( JsonObject dto ){
+    @Operation(summary = "Creates an IP group",
+            description = "Creates a global IP group from the supplied JSON and assigns an available persisted group alias.")
+    public Response postIpGroup(
+            @RequestBody(description = "IP group definition with alias and IP address ranges.")
+            JsonObject dto){
         try {
            IpGroup grp = new JsonParser().parseIpGroup(dto);
             grp.setGroupProvider( ipGroupPrv );
@@ -89,7 +98,13 @@ public Response postIpGroup( JsonObject dto ){
      */
     @PUT
     @Path("ip/{group}")
-    public Response putIpGroups( @PathParam("group") String groupName, JsonObject dto ){
+    @Operation(summary = "Creates or replaces an IP group",
+            description = "Creates or replaces a global IP group with the specified group alias.")
+    public Response putIpGroups(
+            @Parameter(description = "IP group alias to create or replace.", required = true)
+            @PathParam("group") String groupName,
+            @RequestBody(description = "IP group definition with IP address ranges.")
+            JsonObject dto){
         try {
             if ( groupName == null || groupName.trim().isEmpty() ) {
                 return badRequest("Group name cannot be empty");
@@ -112,6 +127,8 @@ public Response putIpGroups( @PathParam("group") String groupName, JsonObject dt
 
     @GET
     @Path("ip")
+    @Operation(summary = "Lists IP groups",
+            description = "Returns all global IP groups as JSON.")
     public Response listIpGroups() {
         return ok( ipGroupPrv.findGlobalGroups()
                              .stream().map(g->json(g)).collect(toJsonArray()) );
@@ -119,7 +136,11 @@ public Response listIpGroups() {
 
     @GET
     @Path("ip/{group}")
-    public Response getIpGroup( @PathParam("group") String groupIdtf ) {
+    @Operation(summary = "Returns an IP group",
+            description = "Returns a global IP group identified by numeric id or alias.")
+    public Response getIpGroup(
+            @Parameter(description = "IP group numeric id or alias.", required = true)
+            @PathParam("group") String groupIdtf) {
         IpGroup grp;
         if ( isNumeric(groupIdtf) ) {
             grp = ipGroupPrv.get( Long.parseLong(groupIdtf) );
@@ -132,7 +153,11 @@ public Response getIpGroup( @PathParam("group") String groupIdtf ) {
 
     @DELETE
     @Path("ip/{group}")
-    public Response deleteIpGroup( @PathParam("group") String groupIdtf ) {
+    @Operation(summary = "Deletes an IP group",
+            description = "Deletes a global IP group identified by numeric id or alias.")
+    public Response deleteIpGroup(
+            @Parameter(description = "IP group numeric id or alias.", required = true)
+            @PathParam("group") String groupIdtf) {
         IpGroup grp;
         if ( isNumeric(groupIdtf) ) {
             grp = ipGroupPrv.get( Long.parseLong(groupIdtf) );
@@ -162,6 +187,8 @@ public Response deleteIpGroup( @PathParam("group") String groupIdtf ) {
 
     @GET
     @Path("shib")
+    @Operation(summary = "Lists Shibboleth groups",
+            description = "Returns all global Shibboleth groups as JSON.")
     public Response listShibGroups() {
         JsonArrayBuilder arrBld = Json.createArrayBuilder();
         for (ShibGroup g : shibGroupPrv.findGlobalGroups()) {
@@ -172,7 +199,11 @@ public Response listShibGroups() {
 
     @POST
     @Path("shib")
-    public Response createShibGroup(JsonObject shibGroupInput) {
+    @Operation(summary = "Creates a Shibboleth group",
+            description = "Creates a Shibboleth group from name, attribute, and pattern values in the supplied JSON.")
+    public Response createShibGroup(
+            @RequestBody(description = "Shibboleth group JSON containing name, attribute, and pattern.")
+            JsonObject shibGroupInput) {
         String expectedNameKey = "name";
         JsonString name = shibGroupInput.getJsonString(expectedNameKey);
         if (name == null) {
@@ -199,7 +230,11 @@ public Response createShibGroup(JsonObject shibGroupInput) {
 
     @DELETE
     @Path("shib/{primaryKey}")
-    public Response deleteShibGroup( @PathParam("primaryKey") String id ) {
+    @Operation(summary = "Deletes a Shibboleth group",
+            description = "Deletes the Shibboleth group with the specified primary key.")
+    public Response deleteShibGroup(
+            @Parameter(description = "Primary key of the Shibboleth group to delete.", required = true)
+            @PathParam("primaryKey") String id) {
         ShibGroup doomed = shibGroupPrv.get(id);
         if (doomed != null) {
             boolean deleted;
@@ -228,7 +263,11 @@ public Response deleteShibGroup( @PathParam("primaryKey") String id ) {
      */
     @POST
     @Path("domain")
-    public Response createMailDomainGroup(JsonObject dto) throws JsonParseException {
+    @Operation(summary = "Creates a mail-domain group",
+            description = "Creates a global mail-domain group from the supplied JSON and refreshes mail-domain group membership.")
+    public Response createMailDomainGroup(
+            @RequestBody(description = "Mail-domain group definition with alias and domain matching rules.")
+            JsonObject dto) throws JsonParseException {
         MailDomainGroup grp = new JsonParser().parseMailDomainGroup(dto);
         mailDomainGroupPrv.saveOrUpdate(Optional.empty(), grp);
         mailDomainGroupPrv.updateGroups();
@@ -245,7 +284,13 @@ public Response createMailDomainGroup(JsonObject dto) throws JsonParseException
      */
     @PUT
     @Path("domain/{groupAlias}")
-    public Response updateMailDomainGroups(@PathParam("groupAlias") String groupAlias, JsonObject dto) throws JsonParseException {
+    @Operation(summary = "Creates or replaces a mail-domain group",
+            description = "Creates or replaces a global mail-domain group with the specified alias and refreshes mail-domain group membership.")
+    public Response updateMailDomainGroups(
+            @Parameter(description = "Mail-domain group alias to create or replace.", required = true)
+            @PathParam("groupAlias") String groupAlias,
+            @RequestBody(description = "Mail-domain group definition with domain matching rules.")
+            JsonObject dto) throws JsonParseException {
         if ( groupAlias == null || groupAlias.trim().isEmpty() ) {
             return badRequest("Group name cannot be empty");
         }
@@ -262,6 +307,8 @@ public Response updateMailDomainGroups(@PathParam("groupAlias") String groupAlia
     
     @GET
     @Path("domain")
+    @Operation(summary = "Lists mail-domain groups",
+            description = "Returns all global mail-domain groups as JSON.")
     public Response listMailDomainGroups() {
         return ok( mailDomainGroupPrv.findGlobalGroups()
             .stream().map(g->json(g)).collect(toJsonArray()) );
@@ -269,14 +316,22 @@ public Response listMailDomainGroups() {
     
     @GET
     @Path("domain/{groupAlias}")
-    public Response getMailDomainGroup(@PathParam("groupAlias") String groupAlias) {
+    @Operation(summary = "Returns a mail-domain group",
+            description = "Returns the global mail-domain group with the specified alias.")
+    public Response getMailDomainGroup(
+            @Parameter(description = "Mail-domain group alias to return.", required = true)
+            @PathParam("groupAlias") String groupAlias) {
         MailDomainGroup grp = mailDomainGroupPrv.get(groupAlias);
         return (grp == null) ? notFound( "Group " + groupAlias + " not found") : ok(json(grp));
     }
     
     @DELETE
     @Path("domain/{groupAlias}")
-    public Response deleteMailDomainGroup(@PathParam("groupAlias") String groupAlias) {
+    @Operation(summary = "Deletes a mail-domain group",
+            description = "Deletes the global mail-domain group with the specified alias and refreshes mail-domain group membership.")
+    public Response deleteMailDomainGroup(
+            @Parameter(description = "Mail-domain group alias to delete.", required = true)
+            @PathParam("groupAlias") String groupAlias) {
         mailDomainGroupPrv.delete(groupAlias);
         mailDomainGroupPrv.updateGroups();
         return ok("Group " + groupAlias + " deleted.");
diff --git a/src/main/java/edu/harvard/iq/dataverse/api/Guestbooks.java b/src/main/java/edu/harvard/iq/dataverse/api/Guestbooks.java
index 160874838d0..0d71594bf18 100644
--- a/src/main/java/edu/harvard/iq/dataverse/api/Guestbooks.java
+++ b/src/main/java/edu/harvard/iq/dataverse/api/Guestbooks.java
@@ -31,8 +31,15 @@
 import java.util.logging.Logger;
 
 import static edu.harvard.iq.dataverse.util.json.JsonPrinter.json;
+import org.eclipse.microprofile.openapi.annotations.Operation;
+import org.eclipse.microprofile.openapi.annotations.parameters.Parameter;
+import org.eclipse.microprofile.openapi.annotations.parameters.RequestBody;
+import org.eclipse.microprofile.openapi.annotations.security.SecurityRequirement;
+import org.eclipse.microprofile.openapi.annotations.tags.Tag;
 
 @Path("guestbooks")
+@SecurityRequirement(name = "DataverseApiKey")
+@Tag(name = "Dataverses", description = "Dataverse collection metadata and administration operations.")
 public class Guestbooks extends AbstractApiBean {
 
     private static final Logger logger = Logger.getLogger(Guestbooks.class.getCanonicalName());
@@ -45,7 +52,11 @@ public class Guestbooks extends AbstractApiBean {
     @GET
     @AuthRequired
     @Path("{id}")
-    public Response getGuestbook(@Context ContainerRequestContext crc, @PathParam("id") Long id) {
+    @Operation(summary = "Returns a guestbook",
+            description = "Returns the guestbook with the specified numeric id.")
+    public Response getGuestbook(@Context ContainerRequestContext crc,
+            @Parameter(description = "Numeric id of the guestbook to return.", required = true)
+            @PathParam("id") Long id) {
         return response( req -> {
             final Guestbook retrieved = guestbookService.find(id);
             if (retrieved != null) {
@@ -60,7 +71,15 @@ public Response getGuestbook(@Context ContainerRequestContext crc, @PathParam("i
     @GET
     @AuthRequired
     @Path("{identifier}/list")
-    public Response getGuestbooks(@Context ContainerRequestContext crc, @PathParam("identifier") String identifier, @QueryParam("includeInherited") boolean includeInherited, @QueryParam("includeStats") boolean includeStats) {
+    @Operation(summary = "Lists guestbooks for a dataverse",
+            description = "Returns guestbooks configured for a dataverse, optionally including inherited guestbooks and usage statistics.")
+    public Response getGuestbooks(@Context ContainerRequestContext crc,
+            @Parameter(description = "Dataverse alias whose guestbooks are listed.", required = true)
+            @PathParam("identifier") String identifier,
+            @Parameter(description = "Include guestbooks inherited from parent dataverses.")
+            @QueryParam("includeInherited") boolean includeInherited,
+            @Parameter(description = "Include guestbook usage and response counts.")
+            @QueryParam("includeStats") boolean includeStats) {
         return response( req -> {
             Dataverse dataverse = findDataverseOrDie(identifier);
             final Long dataverseId = dataverse.getId();
@@ -87,7 +106,13 @@ public Response getGuestbooks(@Context ContainerRequestContext crc, @PathParam("
     @POST
     @AuthRequired
     @Path("{identifier}")
-    public Response createGuestbook(@Context ContainerRequestContext crc, @PathParam("identifier") String identifier, String jsonBody) {
+    @Operation(summary = "Creates a guestbook",
+            description = "Creates a guestbook in the specified dataverse when the requester can edit that dataverse.")
+    public Response createGuestbook(@Context ContainerRequestContext crc,
+            @Parameter(description = "Dataverse alias where the guestbook is created.", required = true)
+            @PathParam("identifier") String identifier,
+            @RequestBody(description = "Guestbook JSON definition to parse and create.")
+            String jsonBody) {
 
         try {
             Dataverse dataverse = findDataverseOrDie(identifier);
@@ -122,7 +147,15 @@ public Response createGuestbook(@Context ContainerRequestContext crc, @PathParam
     @PUT
     @AuthRequired
     @Path("{identifier}/{id}/enabled")
-    public Response enableGuestbook(@Context ContainerRequestContext crc, @PathParam("identifier") String identifier, @PathParam("id") String id, String body) {
+    @Operation(summary = "Sets guestbook enabled state",
+            description = "Updates whether a guestbook in the specified dataverse is enabled.")
+    public Response enableGuestbook(@Context ContainerRequestContext crc,
+            @Parameter(description = "Dataverse alias containing the guestbook.", required = true)
+            @PathParam("identifier") String identifier,
+            @Parameter(description = "Numeric id of the guestbook to update.", required = true)
+            @PathParam("id") String id,
+            @RequestBody(description = "Boolean text indicating whether the guestbook is enabled.")
+            String body) {
         body = body.trim();
         if (!Util.isBoolean(body)) {
             return badRequest("Illegal value '" + body + "'. Use 'true' or 'false'");
diff --git a/src/main/java/edu/harvard/iq/dataverse/api/HarvestingClients.java b/src/main/java/edu/harvard/iq/dataverse/api/HarvestingClients.java
index e4300099244..12cd408d440 100644
--- a/src/main/java/edu/harvard/iq/dataverse/api/HarvestingClients.java
+++ b/src/main/java/edu/harvard/iq/dataverse/api/HarvestingClients.java
@@ -38,8 +38,15 @@
 import jakarta.ws.rs.container.ContainerRequestContext;
 import jakarta.ws.rs.core.Context;
 import jakarta.ws.rs.core.Response;
+import org.eclipse.microprofile.openapi.annotations.Operation;
+import org.eclipse.microprofile.openapi.annotations.parameters.Parameter;
+import org.eclipse.microprofile.openapi.annotations.parameters.RequestBody;
+import org.eclipse.microprofile.openapi.annotations.security.SecurityRequirement;
+import org.eclipse.microprofile.openapi.annotations.tags.Tag;
 
 @Path("harvest/clients")
+@SecurityRequirement(name = "DataverseApiKey")
+@Tag(name = "Admin", description = "Administrative Dataverse operations.")
 public class HarvestingClients extends AbstractApiBean {
 
     
@@ -60,7 +67,11 @@ public class HarvestingClients extends AbstractApiBean {
     @GET
     @AuthRequired
     @Path("/")
-    public Response harvestingClients(@Context ContainerRequestContext crc, @QueryParam("key") String apiKey) throws IOException {
+    @Operation(summary = "Lists harvesting clients",
+            description = "Returns harvesting client configurations visible to the authenticated requester.")
+    public Response harvestingClients(@Context ContainerRequestContext crc,
+            @Parameter(hidden = true)
+            @QueryParam("key") String apiKey) throws IOException {
         
         List<HarvestingClient> harvestingClients = null; 
         try {
@@ -103,7 +114,13 @@ public Response harvestingClients(@Context ContainerRequestContext crc, @QueryPa
     @GET
     @AuthRequired
     @Path("{nickName}")
-    public Response harvestingClient(@Context ContainerRequestContext crc, @PathParam("nickName") String nickName, @QueryParam("key") String apiKey) throws IOException {
+    @Operation(summary = "Returns a harvesting client",
+            description = "Returns the harvesting client configuration with the specified nickname when the requester is authorized to view it.")
+    public Response harvestingClient(@Context ContainerRequestContext crc,
+            @Parameter(description = "Harvesting client nickname to return.", required = true)
+            @PathParam("nickName") String nickName,
+            @Parameter(hidden = true)
+            @QueryParam("key") String apiKey) throws IOException {
         
         HarvestingClient harvestingClient = null; 
         try {
@@ -153,7 +170,15 @@ public Response harvestingClient(@Context ContainerRequestContext crc, @PathPara
     @POST
     @AuthRequired
     @Path("{nickName}")
-    public Response createHarvestingClient(@Context ContainerRequestContext crc, String jsonBody, @PathParam("nickName") String nickName, @QueryParam("key") String apiKey) throws IOException, JsonParseException {
+    @Operation(summary = "Creates a harvesting client",
+            description = "Creates a harvesting client with the specified nickname when the authenticated user is a superuser.")
+    public Response createHarvestingClient(@Context ContainerRequestContext crc,
+            @RequestBody(description = "Harvesting client JSON containing dataverse alias, harvest URL, archive URL, metadata format, and optional settings.")
+            String jsonBody,
+            @Parameter(description = "Nickname assigned to the harvesting client.", required = true)
+            @PathParam("nickName") String nickName,
+            @Parameter(hidden = true)
+            @QueryParam("key") String apiKey) throws IOException, JsonParseException {
         // Per the discussion during the QA of PR #9174, we decided to make 
         // the create/edit APIs superuser-only (the delete API was already so)
         try {
@@ -238,7 +263,15 @@ public Response createHarvestingClient(@Context ContainerRequestContext crc, Str
     @PUT
     @AuthRequired
     @Path("{nickName}")
-    public Response modifyHarvestingClient(@Context ContainerRequestContext crc, String jsonBody, @PathParam("nickName") String nickName, @QueryParam("key") String apiKey) throws IOException, JsonParseException {
+    @Operation(summary = "Updates a harvesting client",
+            description = "Updates editable harvesting client fields when the authenticated user is a superuser.")
+    public Response modifyHarvestingClient(@Context ContainerRequestContext crc,
+            @RequestBody(description = "Harvesting client update JSON containing editable fields such as harvest URL, archive URL, metadata format, set, and custom headers.")
+            String jsonBody,
+            @Parameter(description = "Nickname of the harvesting client to update.", required = true)
+            @PathParam("nickName") String nickName,
+            @Parameter(hidden = true)
+            @QueryParam("key") String apiKey) throws IOException, JsonParseException {
         try {
             User u = getRequestUser(crc);
             if ((!(u instanceof AuthenticatedUser) || !u.isSuperuser())) {
@@ -321,7 +354,11 @@ public Response modifyHarvestingClient(@Context ContainerRequestContext crc, Str
     @DELETE
     @AuthRequired
     @Path("{nickName}")
-    public Response deleteHarvestingClient(@Context ContainerRequestContext crc, @PathParam("nickName") String nickName) throws IOException {
+    @Operation(summary = "Deletes a harvesting client",
+            description = "Starts asynchronous deletion of a harvesting client when the authenticated user is a superuser and no harvest or delete is already in progress.")
+    public Response deleteHarvestingClient(@Context ContainerRequestContext crc,
+            @Parameter(description = "Nickname of the harvesting client to delete.", required = true)
+            @PathParam("nickName") String nickName) throws IOException {
         // Deleting a client can take a while (if there's a large amnount of 
         // harvested content associated with it). So instead of calling the command
         // directly, we will be calling an async. service bean method. 
@@ -379,7 +416,13 @@ public Response deleteHarvestingClient(@Context ContainerRequestContext crc, @Pa
     @POST
     @AuthRequired
     @Path("{nickName}/run")
-    public Response startHarvestingJob(@Context ContainerRequestContext crc, @PathParam("nickName") String clientNickname, @QueryParam("key") String apiKey) throws IOException {
+    @Operation(summary = "Starts a harvesting job",
+            description = "Starts an asynchronous harvesting job for the specified client when the authenticated user is a superuser.")
+    public Response startHarvestingJob(@Context ContainerRequestContext crc,
+            @Parameter(description = "Nickname of the harvesting client to run.", required = true)
+            @PathParam("nickName") String clientNickname,
+            @Parameter(hidden = true)
+            @QueryParam("key") String apiKey) throws IOException {
         
         try {
             AuthenticatedUser authenticatedUser = null; 
diff --git a/src/main/java/edu/harvard/iq/dataverse/api/HarvestingServer.java b/src/main/java/edu/harvard/iq/dataverse/api/HarvestingServer.java
index 308b910c425..23b6dd744c3 100644
--- a/src/main/java/edu/harvard/iq/dataverse/api/HarvestingServer.java
+++ b/src/main/java/edu/harvard/iq/dataverse/api/HarvestingServer.java
@@ -35,6 +35,11 @@
 import jakarta.ws.rs.core.Context;
 import jakarta.ws.rs.core.Response;
 import org.apache.commons.lang3.StringUtils;
+import org.eclipse.microprofile.openapi.annotations.Operation;
+import org.eclipse.microprofile.openapi.annotations.parameters.Parameter;
+import org.eclipse.microprofile.openapi.annotations.parameters.RequestBody;
+import org.eclipse.microprofile.openapi.annotations.security.SecurityRequirement;
+import org.eclipse.microprofile.openapi.annotations.tags.Tag;
 
 /**
  *
@@ -42,6 +47,7 @@
  */
 @Stateless
 @Path("harvest/server/oaisets")
+@Tag(name = "Admin", description = "Administrative Dataverse operations.")
 public class HarvestingServer extends AbstractApiBean {
     @EJB
     OAISetServiceBean oaiSetService;
@@ -53,7 +59,11 @@ public class HarvestingServer extends AbstractApiBean {
     // Create, Modify, and Delete we should also add them here.
     
     @GET
-    public Response oaiSets(@QueryParam("key") String apiKey) throws IOException {
+    @Operation(summary = "Lists OAI sets",
+            description = "Returns all configured OAI sets with name, spec, description, definition, and version.")
+    public Response oaiSets(
+            @Parameter(description = "Legacy key value accepted by the endpoint.")
+            @QueryParam("key") String apiKey) throws IOException {
     
         List<OAISet> oaiSets = null;
         try {
@@ -78,7 +88,13 @@ public Response oaiSets(@QueryParam("key") String apiKey) throws IOException {
     
     @GET
     @Path("{specname}")
-    public Response oaiSet(@PathParam("specname") String spec, @QueryParam("key") String apiKey) throws IOException {
+    @Operation(summary = "Returns an OAI set",
+            description = "Returns the OAI set with the specified set specification name.")
+    public Response oaiSet(
+            @Parameter(description = "OAI set specification name to return.", required = true)
+            @PathParam("specname") String spec,
+            @Parameter(description = "Legacy key value accepted by the endpoint.")
+            @QueryParam("key") String apiKey) throws IOException {
         
         OAISet set = null;  
         try {
@@ -109,7 +125,14 @@ public Response oaiSet(@PathParam("specname") String spec, @QueryParam("key") St
     @POST
     @AuthRequired
     @Path("/add")
-    public Response createOaiSet(@Context ContainerRequestContext crc, String jsonBody, @QueryParam("key") String apiKey) throws IOException, JsonParseException {
+    @SecurityRequirement(name = "DataverseApiKey")
+    @Operation(summary = "Creates an OAI set",
+            description = "Creates an OAI set from name, definition, and optional description JSON when the authenticated user is a superuser.")
+    public Response createOaiSet(@Context ContainerRequestContext crc,
+            @RequestBody(description = "OAI set JSON containing name, definition, and optional description.")
+            String jsonBody,
+            @Parameter(hidden = true)
+            @QueryParam("key") String apiKey) throws IOException, JsonParseException {
         /*
 	     * authorization modeled after the UI (aka HarvestingSetsPage)
          */
@@ -179,7 +202,16 @@ public Response createOaiSet(@Context ContainerRequestContext crc, String jsonBo
     @PUT
     @AuthRequired
     @Path("{specname}")
-    public Response modifyOaiSet(@Context ContainerRequestContext crc, String jsonBody, @PathParam("specname") String spec, @QueryParam("key") String apiKey) throws IOException, JsonParseException {
+    @SecurityRequirement(name = "DataverseApiKey")
+    @Operation(summary = "Updates an OAI set",
+            description = "Updates the definition or description of an OAI set when the authenticated user is a superuser.")
+    public Response modifyOaiSet(@Context ContainerRequestContext crc,
+            @RequestBody(description = "OAI set update JSON containing definition, description, or both.")
+            String jsonBody,
+            @Parameter(description = "OAI set specification name to update.", required = true)
+            @PathParam("specname") String spec,
+            @Parameter(hidden = true)
+            @QueryParam("key") String apiKey) throws IOException, JsonParseException {
 
         AuthenticatedUser dvUser;
         try {
@@ -232,7 +264,14 @@ public Response modifyOaiSet(@Context ContainerRequestContext crc, String jsonBo
     @DELETE
     @AuthRequired
     @Path("{specname}")
-    public Response deleteOaiSet(@Context ContainerRequestContext crc, @PathParam("specname") String spec, @QueryParam("key") String apiKey) {
+    @SecurityRequirement(name = "DataverseApiKey")
+    @Operation(summary = "Deletes an OAI set",
+            description = "Marks an OAI set for deletion and removes it when the authenticated user is a superuser.")
+    public Response deleteOaiSet(@Context ContainerRequestContext crc,
+            @Parameter(description = "OAI set specification name to delete.", required = true)
+            @PathParam("specname") String spec,
+            @Parameter(hidden = true)
+            @QueryParam("key") String apiKey) {
         
         AuthenticatedUser dvUser;
         try {
@@ -269,7 +308,13 @@ public Response deleteOaiSet(@Context ContainerRequestContext crc, @PathParam("s
     
     @GET
     @Path("{specname}/datasets")
-    public Response oaiSetListDatasets(@PathParam("specname") String spec, @QueryParam("key") String apiKey) throws IOException {
+    @Operation(summary = "Lists datasets in an OAI set",
+            description = "Validates that the specified OAI set exists and returns the current placeholder response for dataset listing.")
+    public Response oaiSetListDatasets(
+            @Parameter(description = "OAI set specification name whose datasets are requested.", required = true)
+            @PathParam("specname") String spec,
+            @Parameter(description = "Legacy key value accepted by the endpoint.")
+            @QueryParam("key") String apiKey) throws IOException {
         OAISet set = null;  
         try {
             set = oaiSetService.findBySpec(spec);
diff --git a/src/main/java/edu/harvard/iq/dataverse/api/Index.java b/src/main/java/edu/harvard/iq/dataverse/api/Index.java
index f83506c7e27..290925c26b3 100644
--- a/src/main/java/edu/harvard/iq/dataverse/api/Index.java
+++ b/src/main/java/edu/harvard/iq/dataverse/api/Index.java
@@ -67,8 +67,12 @@
 import jakarta.ws.rs.core.Response;
 import jakarta.ws.rs.core.Response.Status;
 import org.apache.solr.client.solrj.SolrServerException;
+import org.eclipse.microprofile.openapi.annotations.Operation;
+import org.eclipse.microprofile.openapi.annotations.parameters.Parameter;
+import org.eclipse.microprofile.openapi.annotations.tags.Tag;
 
 @Path("admin/index")
+@Tag(name = "Admin", description = "Administrative Dataverse operations.")
 public class Index extends AbstractApiBean {
 
     private static final Logger logger = Logger.getLogger(Index.class.getCanonicalName());
@@ -104,13 +108,29 @@ public class Index extends AbstractApiBean {
     public static String permsIndexed = "permsIndexed";
 
     @GET
-    public Response indexAllOrSubset(@QueryParam("numPartitions") Long numPartitionsSelected, @QueryParam("partitionIdToProcess") Long partitionIdToProcess, @QueryParam("previewOnly") boolean previewOnly) {
+    @Operation(summary = "Starts indexing all content",
+            description = "Starts indexing all dataverses and datasets or one selected partition, with an option to preview the selected workload.")
+    public Response indexAllOrSubset(
+            @Parameter(description = "Number of index partitions to divide the workload into.")
+            @QueryParam("numPartitions") Long numPartitionsSelected,
+            @Parameter(description = "Partition id to process when the workload is divided into partitions.")
+            @QueryParam("partitionIdToProcess") Long partitionIdToProcess,
+            @Parameter(description = "Preview the selected indexing workload without starting indexing.")
+            @QueryParam("previewOnly") boolean previewOnly) {
         return indexAllOrSubset(numPartitionsSelected, partitionIdToProcess, false, previewOnly);
     }
 
     @GET
     @Path("continue")
-    public Response indexAllOrSubsetContinue(@QueryParam("numPartitions") Long numPartitionsSelected, @QueryParam("partitionIdToProcess") Long partitionIdToProcess, @QueryParam("previewOnly") boolean previewOnly) {
+    @Operation(summary = "Continues indexing unindexed content",
+            description = "Starts indexing one selected partition while skipping content that has already been indexed, with an option to preview the selected workload.")
+    public Response indexAllOrSubsetContinue(
+            @Parameter(description = "Number of index partitions to divide the workload into.")
+            @QueryParam("numPartitions") Long numPartitionsSelected,
+            @Parameter(description = "Partition id to process when the workload is divided into partitions.")
+            @QueryParam("partitionIdToProcess") Long partitionIdToProcess,
+            @Parameter(description = "Preview the selected indexing workload without starting indexing.")
+            @QueryParam("previewOnly") boolean previewOnly) {
         return indexAllOrSubset(numPartitionsSelected, partitionIdToProcess, true, previewOnly);
     }
 
@@ -208,6 +228,8 @@ private Response indexAllOrSubset(Long numPartitionsSelected, Long partitionIdTo
 
     @GET
     @Path("clear")
+    @Operation(summary = "Clears the Solr index",
+            description = "Clears all Solr documents and resets stored index timestamps.")
     public Response clearSolrIndex() {
         try {
             JsonObjectBuilder response = SolrIndexService.deleteAllFromSolrAndResetIndexTimes();
@@ -219,7 +241,13 @@ public Response clearSolrIndex() {
     
     @GET
     @Path("{type}/{id}")
-    public Response indexTypeById(@PathParam("type") String type, @PathParam("id") Long id) {
+    @Operation(summary = "Starts indexing one object",
+            description = "Starts reindexing a dataverse, dataset, or file by numeric id, or removes a stale Solr document when the object is missing.")
+    public Response indexTypeById(
+            @Parameter(description = "Object type to index: dataverses, datasets, or files.", required = true)
+            @PathParam("type") String type,
+            @Parameter(description = "Numeric id of the object to index.", required = true)
+            @PathParam("id") Long id) {
         try {
             if (type.equals("dataverses")) {
                 Dataverse dataverse = dataverseService.find(id);
@@ -296,7 +324,11 @@ public Response indexTypeById(@PathParam("type") String type, @PathParam("id") L
 
     @GET
     @Path("dataset")
-    public Response indexDatasetByPersistentId(@QueryParam("persistentId") String persistentId) {
+    @Operation(summary = "Starts indexing a dataset by PID",
+            description = "Looks up a dataset by persistent identifier, starts dataset indexing, and returns version identifiers for the dataset.")
+    public Response indexDatasetByPersistentId(
+            @Parameter(description = "Persistent identifier of the dataset to index.", required = true)
+            @QueryParam("persistentId") String persistentId) {
         if (persistentId == null) {
             return error(Status.BAD_REQUEST, "No persistent id given.");
         }
@@ -337,7 +369,11 @@ public Response indexDatasetByPersistentId(@QueryParam("persistentId") String pe
      */
     @DELETE
     @Path("datasets/{id}")
-    public Response clearDatasetFromIndex(@PathParam("id") Long id) {
+    @Operation(summary = "Clears a dataset from the Solr index",
+            description = "Removes the Solr document for the specified dataset id, even when the dataset no longer exists in the database.")
+    public Response clearDatasetFromIndex(
+            @Parameter(description = "Numeric id of the dataset to remove from Solr.", required = true)
+            @PathParam("id") Long id) {
         Dataset dataset = datasetService.find(id);
         // We'll attempt to delete the Solr document regardless of whether the 
         // dataset exists in the database: 
diff --git a/src/main/java/edu/harvard/iq/dataverse/api/Info.java b/src/main/java/edu/harvard/iq/dataverse/api/Info.java
index ccb1e6fdf02..78edf67ad5a 100644
--- a/src/main/java/edu/harvard/iq/dataverse/api/Info.java
+++ b/src/main/java/edu/harvard/iq/dataverse/api/Info.java
@@ -27,7 +27,7 @@
 import org.eclipse.microprofile.openapi.annotations.tags.Tag;
 
 @Path("info")
-@Tag(name = "info", description = "General information about the Dataverse installation.")
+@Tag(name = "Info", description = "General information about the Dataverse installation.")
 public class Info extends AbstractApiBean {
 
     @EJB
@@ -40,37 +40,48 @@ public class Info extends AbstractApiBean {
 
     @GET
     @Path("settings/:DatasetPublishPopupCustomText")
+    @Operation(summary = "Returns dataset publish popup text",
+            description = "Returns the custom text shown in the dataset publish popup when the setting is configured.")
     public Response getDatasetPublishPopupCustomText() {
         return getSettingResponseByKey(SettingsServiceBean.Key.DatasetPublishPopupCustomText);
     }
 
     @GET
     @Path("settings/:DatasetSubmitForReviewPopupCustomText")
+    @Operation(summary = "Returns dataset review popup text",
+            description = "Returns the custom text shown when a dataset is submitted for review and the setting is configured.")
     public Response DatasetSubmitForReviewPopupCustomText() {
         return getSettingResponseByKey(SettingsServiceBean.Key.DatasetSubmitForReviewPopupCustomText);
     }
 
     @GET
     @Path("settings/:PublishDatasetDisclaimerText")
+    @Operation(summary = "Returns dataset publish disclaimer text",
+            description = "Returns the disclaimer text shown during dataset publication when the setting is configured.")
     public Response getPublishDatasetDisclaimerText() {
         return getSettingResponseByKey(SettingsServiceBean.Key.PublishDatasetDisclaimerText);
     }
 
     @GET
     @Path("settings/:SubmitForReviewDatasetDisclaimerText")
+    @Operation(summary = "Returns dataset review disclaimer text",
+            description = "Returns the disclaimer text shown when a dataset is submitted for review and the setting is configured.")
     public Response getSubmitForReviewDatasetDisclaimerText() {
         return getSettingResponseByKey(SettingsServiceBean.Key.SubmitForReviewDatasetDisclaimerText);
     }
 
     @GET
     @Path("settings/:MaxEmbargoDurationInMonths")
+    @Operation(summary = "Returns the maximum embargo duration",
+            description = "Returns the configured maximum embargo duration in months when the setting is configured.")
     public Response getMaxEmbargoDurationInMonths() {
         return getSettingResponseByKey(SettingsServiceBean.Key.MaxEmbargoDurationInMonths);
     }
 
     @GET
     @Path("version")
-    @Operation(summary = "Get version and build information", description = "Get version and build information")
+    @Operation(summary = "Returns version and build information",
+            description = "Returns the Dataverse application version and build identifier.")
     @APIResponse(responseCode = "200",
                  description = "Version and build information")
     public Response getInfo() {
@@ -85,12 +96,16 @@ public Response getInfo() {
 
     @GET
     @Path("server")
+    @Operation(summary = "Returns the server name",
+            description = "Returns the configured fully qualified domain name for this Dataverse installation.")
     public Response getServer() {
         return ok(JvmSettings.FQDN.lookup());
     }
 
     @GET
     @Path("applicationTermsOfUse")
+    @Operation(summary = "Returns application terms of use",
+            description = "Returns the general application terms of use that users agree to during signup, optionally localized by language code.")
     @APIResponse(responseCode = "200",
                  description = "Application Terms of Use (General Terms of Use) that must be agreed to at signup.")
     public Response getApplicationTermsOfUse(
@@ -104,18 +119,24 @@ public Response getApplicationTermsOfUse(
 
     @GET
     @Path("apiTermsOfUse")
+    @Operation(summary = "Returns API terms of use",
+            description = "Returns the configured API terms of use for this Dataverse installation.")
     public Response getTermsOfUse() {
         return ok(systemConfig.getApiTermsOfUse());
     }
 
     @GET
     @Path("settings/incompleteMetadataViaApi")
+    @Operation(summary = "Returns incomplete metadata API policy",
+            description = "Returns whether API requests may create or update datasets with incomplete metadata.")
     public Response getAllowsIncompleteMetadata() {
         return ok(JvmSettings.API_ALLOW_INCOMPLETE_METADATA.lookupOptional(Boolean.class).orElse(false));
     }
 
     @GET
     @Path("zipDownloadLimit")
+    @Operation(summary = "Returns the ZIP download limit",
+            description = "Returns the configured maximum size for ZIP downloads in bytes.")
     public Response getZipDownloadLimit() {
         long zipDownloadLimit = SystemConfig.getLongLimitFromStringOrDefault(settingsSvc.getValueForKey(SettingsServiceBean.Key.ZipDownloadLimit), SystemConfig.defaultZipDownloadLimit);
         return ok(zipDownloadLimit);
@@ -123,6 +144,8 @@ public Response getZipDownloadLimit() {
 
     @GET
     @Path("exportFormats")
+    @Operation(summary = "Lists export formats",
+            description = "Returns dataset export formats with display name, media type, harvestability, user-interface visibility, and XML metadata when available.")
     public Response getExportFormats() {
         JsonObjectBuilder responseModel = Json.createObjectBuilder();
         ExportService instance = ExportService.getInstance();
@@ -149,7 +172,11 @@ public Response getExportFormats() {
 
     @GET
     @Path("settings/customization/{customizationFileType}")
-    public Response getCustomizationFile(@PathParam("customizationFileType") String customizationFileType) {
+    @Operation(summary = "Returns a customization file",
+            description = "Returns the configured customization file for the requested customization type.")
+    public Response getCustomizationFile(
+            @Parameter(description = "Customization file type to retrieve.", required = true)
+            @PathParam("customizationFileType") String customizationFileType) {
         String type = customizationFileType != null ? customizationFileType.toLowerCase() : "";
         if (!CustomizationConstants.validTypes.contains(type)) {
             return badRequest("Customization type unknown or missing. Must be one of the following: " + CustomizationConstants.validTypes);
diff --git a/src/main/java/edu/harvard/iq/dataverse/api/Licenses.java b/src/main/java/edu/harvard/iq/dataverse/api/Licenses.java
index ab50ebbf2e4..75b3bf82d64 100644
--- a/src/main/java/edu/harvard/iq/dataverse/api/Licenses.java
+++ b/src/main/java/edu/harvard/iq/dataverse/api/Licenses.java
@@ -22,6 +22,11 @@
 import edu.harvard.iq.dataverse.license.License;
 import edu.harvard.iq.dataverse.util.json.JsonPrinter;
 import static edu.harvard.iq.dataverse.util.json.JsonPrinter.json;
+import org.eclipse.microprofile.openapi.annotations.Operation;
+import org.eclipse.microprofile.openapi.annotations.parameters.Parameter;
+import org.eclipse.microprofile.openapi.annotations.parameters.RequestBody;
+import org.eclipse.microprofile.openapi.annotations.security.SecurityRequirement;
+import org.eclipse.microprofile.openapi.annotations.tags.Tag;
 
 /**
  * Where the licenses API calls live.
@@ -30,12 +35,15 @@
  */
 @Stateless
 @Path("licenses")
+@Tag(name = "Licenses", description = "License lookup and administration operations.")
 public class Licenses extends AbstractApiBean {
 
     private static final Logger logger = Logger.getLogger(Licenses.class.getName());
 
     @GET
     @Path("/")
+    @Operation(summary = "Lists licenses",
+            description = "Returns all configured licenses as JSON.")
     public Response getLicenses() {
         JsonArrayBuilder arrayBuilder = Json.createArrayBuilder();
         for (License license : licenseSvc.listAll()) {
@@ -46,7 +54,11 @@ public Response getLicenses() {
 
     @GET
     @Path("/{id}")
-    public Response getLicenseById(@PathParam("id") long id) {
+    @Operation(summary = "Returns a license",
+            description = "Returns the configured license with the specified numeric id.")
+    public Response getLicenseById(
+            @Parameter(description = "Numeric id of the license to return.", required = true)
+            @PathParam("id") long id) {
         License license = licenseSvc.getById(id);
         if (license == null)
             return error(Response.Status.NOT_FOUND, "License with ID " + id + " not found");
@@ -56,7 +68,12 @@ public Response getLicenseById(@PathParam("id") long id) {
     @POST
     @AuthRequired
     @Path("/")
-    public Response addLicense(@Context ContainerRequestContext crc, License license) {
+    @SecurityRequirement(name = "DataverseApiKey")
+    @Operation(summary = "Creates a license",
+            description = "Creates a license when the authenticated user is a superuser and returns the created license location.")
+    public Response addLicense(@Context ContainerRequestContext crc,
+            @RequestBody(description = "License definition to persist, including name, URI, active state, and sort order.")
+            License license) {
         User authenticatedUser;
         try {
             authenticatedUser = getRequestAuthenticatedUserOrDie(crc);
@@ -85,6 +102,8 @@ public Response addLicense(@Context ContainerRequestContext crc, License license
 
     @GET
     @Path("/default")
+    @Operation(summary = "Returns the default license",
+            description = "Returns the numeric id of the configured default license.")
     public Response getDefault() {
         return ok("Default license ID is " + licenseSvc.getDefault().getId());
     }
@@ -92,7 +111,12 @@ public Response getDefault() {
     @PUT
     @AuthRequired
     @Path("/default/{id}")
-    public Response setDefault(@Context ContainerRequestContext crc, @PathParam("id") long id) {
+    @SecurityRequirement(name = "DataverseApiKey")
+    @Operation(summary = "Sets the default license",
+            description = "Sets the specified license as the default when the authenticated user is a superuser.")
+    public Response setDefault(@Context ContainerRequestContext crc,
+            @Parameter(description = "Numeric id of the license to make default.", required = true)
+            @PathParam("id") long id) {
         User authenticatedUser;
         try {
             authenticatedUser = getRequestAuthenticatedUserOrDie(crc);
@@ -124,7 +148,14 @@ public Response setDefault(@Context ContainerRequestContext crc, @PathParam("id"
     @PUT
     @AuthRequired
     @Path("/{id}/:active/{activeState}")
-    public Response setActiveState(@Context ContainerRequestContext crc, @PathParam("id") long id, @PathParam("activeState") boolean active) {
+    @SecurityRequirement(name = "DataverseApiKey")
+    @Operation(summary = "Sets license active state",
+            description = "Updates whether the specified license is active when the authenticated user is a superuser.")
+    public Response setActiveState(@Context ContainerRequestContext crc,
+            @Parameter(description = "Numeric id of the license to update.", required = true)
+            @PathParam("id") long id,
+            @Parameter(description = "New active state for the license.", required = true)
+            @PathParam("activeState") boolean active) {
         User authenticatedUser;
         try {
             authenticatedUser = getRequestAuthenticatedUserOrDie(crc);
@@ -155,7 +186,14 @@ public Response setActiveState(@Context ContainerRequestContext crc, @PathParam(
     @PUT
     @AuthRequired
     @Path("/{id}/:sortOrder/{sortOrder}")
-    public Response setSortOrder(@Context ContainerRequestContext crc, @PathParam("id") long id, @PathParam("sortOrder") long sortOrder) {
+    @SecurityRequirement(name = "DataverseApiKey")
+    @Operation(summary = "Sets license sort order",
+            description = "Updates the sort order for the specified license when the authenticated user is a superuser.")
+    public Response setSortOrder(@Context ContainerRequestContext crc,
+            @Parameter(description = "Numeric id of the license to update.", required = true)
+            @PathParam("id") long id,
+            @Parameter(description = "New sort order value for the license.", required = true)
+            @PathParam("sortOrder") long sortOrder) {
         User authenticatedUser;
         try {
             authenticatedUser = getRequestAuthenticatedUserOrDie(crc);
@@ -187,7 +225,12 @@ public Response setSortOrder(@Context ContainerRequestContext crc, @PathParam("i
     @DELETE
     @AuthRequired
     @Path("/{id}")
-    public Response deleteLicenseById(@Context ContainerRequestContext crc, @PathParam("id") long id) {
+    @SecurityRequirement(name = "DataverseApiKey")
+    @Operation(summary = "Deletes a license",
+            description = "Deletes a non-default license when the authenticated user is a superuser.")
+    public Response deleteLicenseById(@Context ContainerRequestContext crc,
+            @Parameter(description = "Numeric id of the license to delete.", required = true)
+            @PathParam("id") long id) {
         User authenticatedUser;
         try {
             authenticatedUser = getRequestAuthenticatedUserOrDie(crc);
diff --git a/src/main/java/edu/harvard/iq/dataverse/api/LocalContexts.java b/src/main/java/edu/harvard/iq/dataverse/api/LocalContexts.java
index d847adaf116..96432d5b608 100644
--- a/src/main/java/edu/harvard/iq/dataverse/api/LocalContexts.java
+++ b/src/main/java/edu/harvard/iq/dataverse/api/LocalContexts.java
@@ -29,8 +29,13 @@
 import jakarta.ws.rs.core.MediaType;
 import jakarta.ws.rs.core.Response;
 import jakarta.ws.rs.container.ContainerRequestContext;
+import org.eclipse.microprofile.openapi.annotations.Operation;
+import org.eclipse.microprofile.openapi.annotations.parameters.Parameter;
+import org.eclipse.microprofile.openapi.annotations.security.SecurityRequirement;
+import org.eclipse.microprofile.openapi.annotations.tags.Tag;
 
 @Path("localcontexts")
+@Tag(name = "Datasets", description = "Dataset metadata, versions, files, and publishing operations.")
 public class LocalContexts extends AbstractApiBean {
 
     protected static final Logger logger = Logger.getLogger(LocalContexts.class.getName());
@@ -48,7 +53,12 @@ public class LocalContexts extends AbstractApiBean {
     @Path("/datasets/{id}")
     @Produces(MediaType.APPLICATION_JSON)
     @AuthRequired
-    public Response getDatasetLocalContexts(@Context ContainerRequestContext crc, @PathParam("id") String id) {
+    @SecurityRequirement(name = "DataverseApiKey")
+    @Operation(summary = "Finds Local Contexts projects for a dataset",
+            description = "Queries the configured Local Contexts service by dataset DOI and returns matching project information when the requester is allowed to inspect the dataset.")
+    public Response getDatasetLocalContexts(@Context ContainerRequestContext crc,
+            @Parameter(description = "Dataset id or persistent identifier whose DOI is sent to Local Contexts.", required = true)
+            @PathParam("id") String id) {
         try {
             Dataset dataset = findDatasetOrDie(id);
             DataverseRequest req = createDataverseRequest(getRequestUser(crc));
@@ -112,7 +122,13 @@ public Response getDatasetLocalContexts(@Context ContainerRequestContext crc, @P
     @GET
     @Path("/datasets/{id}/{projectId}")
     @Produces(MediaType.APPLICATION_JSON)
-    public Response searchLocalContexts(@PathParam("id") String datasetId, @PathParam("projectId") String projectId) {
+    @Operation(summary = "Returns a Local Contexts project",
+            description = "Returns a Local Contexts project only when the project response includes a DOI matching the specified dataset.")
+    public Response searchLocalContexts(
+            @Parameter(description = "Dataset id or persistent identifier used to validate the Local Contexts project DOI.", required = true)
+            @PathParam("id") String datasetId,
+            @Parameter(description = "Local Contexts project id to retrieve.", required = true)
+            @PathParam("projectId") String projectId) {
         try {
             Dataset dataset = findDatasetOrDie(datasetId);
             String localContextsUrl = JvmSettings.LOCALCONTEXTS_URL.lookupOptional().orElse(null);
@@ -182,4 +198,4 @@ public Response searchLocalContexts(@PathParam("id") String datasetId, @PathPara
             return ex.getResponse();
         }
     }
-}
\ No newline at end of file
+}
diff --git a/src/main/java/edu/harvard/iq/dataverse/api/Logout.java b/src/main/java/edu/harvard/iq/dataverse/api/Logout.java
index e8d8be04459..718a0d16420 100644
--- a/src/main/java/edu/harvard/iq/dataverse/api/Logout.java
+++ b/src/main/java/edu/harvard/iq/dataverse/api/Logout.java
@@ -8,8 +8,11 @@
 import jakarta.ws.rs.POST;
 import jakarta.ws.rs.Path;
 import jakarta.ws.rs.core.Response;
+import org.eclipse.microprofile.openapi.annotations.Operation;
+import org.eclipse.microprofile.openapi.annotations.tags.Tag;
 
 @Path("logout")
+@Tag(name = "Users", description = "User account and authenticated user operations.")
 public class Logout extends AbstractApiBean {
 
     @Inject
@@ -27,6 +30,8 @@ public class Logout extends AbstractApiBean {
      */
     @POST
     @Path("/")
+    @Operation(summary = "Logs out the current session",
+            description = "Clears the authenticated session-cookie user when API session authentication is enabled.")
     public Response logout() {
         if (!FeatureFlags.API_SESSION_AUTH.enabled()) {
             return error(Response.Status.INTERNAL_SERVER_ERROR, "This endpoint is only available when session authentication feature flag is enabled");
diff --git a/src/main/java/edu/harvard/iq/dataverse/api/Mail.java b/src/main/java/edu/harvard/iq/dataverse/api/Mail.java
index 5fac2f30c89..6c60bcd5588 100644
--- a/src/main/java/edu/harvard/iq/dataverse/api/Mail.java
+++ b/src/main/java/edu/harvard/iq/dataverse/api/Mail.java
@@ -6,6 +6,8 @@
 import jakarta.ws.rs.GET;
 import jakarta.ws.rs.Path;
 import jakarta.ws.rs.core.Response;
+import org.eclipse.microprofile.openapi.annotations.Operation;
+import org.eclipse.microprofile.openapi.annotations.tags.Tag;
 
 /**
  *
@@ -13,6 +15,7 @@
  * @author Leonid Andreev
  */
 @Path("mail")
+@Tag(name = "Admin", description = "Administrative Dataverse operations.")
 public class Mail extends AbstractApiBean {
     
     @EJB
@@ -20,6 +23,8 @@ public class Mail extends AbstractApiBean {
     
     @GET
     @Path("notifications")
+    @Operation(summary = "Reports deprecated bulk notification status",
+            description = "Logs the deprecated bulk notification request and returns a message indicating that bulk notification sending is deprecated.")
     public Response sendMail() {
         ActionLogRecord alr = new ActionLogRecord(ActionLogRecord.ActionType.Admin, "sendMail");
        // mailService.bulkSendNotifications();
diff --git a/src/main/java/edu/harvard/iq/dataverse/api/MakeDataCountApi.java b/src/main/java/edu/harvard/iq/dataverse/api/MakeDataCountApi.java
index de8a5b6523d..709d403c568 100644
--- a/src/main/java/edu/harvard/iq/dataverse/api/MakeDataCountApi.java
+++ b/src/main/java/edu/harvard/iq/dataverse/api/MakeDataCountApi.java
@@ -41,11 +41,15 @@
 import jakarta.ws.rs.QueryParam;
 import jakarta.ws.rs.core.Response;
 import jakarta.ws.rs.core.Response.Status;
+import org.eclipse.microprofile.openapi.annotations.Operation;
+import org.eclipse.microprofile.openapi.annotations.parameters.Parameter;
+import org.eclipse.microprofile.openapi.annotations.tags.Tag;
 
 /**
  * Note that there are makeDataCount endpoints in Datasets.java as well.
  */
 @Path("admin/makeDataCount")
+@Tag(name = "Admin", description = "Administrative Dataverse operations.")
 public class MakeDataCountApi extends AbstractApiBean {
 
     private static final Logger logger = Logger.getLogger(MakeDataCountApi.class.getCanonicalName());
@@ -87,6 +91,8 @@ public class MakeDataCountApi extends AbstractApiBean {
      */
     @POST
     @Path("sendToHub")
+    @Operation(summary = "Reports Make Data Count hub submission",
+            description = "Returns a confirmation message for Make Data Count hub submission.")
     public Response sendDataToHub() {
         String msg = "Data has been sent to Make Data Count";
         return ok(msg);
@@ -94,7 +100,13 @@ public Response sendDataToHub() {
 
     @POST
     @Path("{id}/addUsageMetricsFromSushiReport")
-    public Response addUsageMetricsFromSushiReport(@PathParam("id") String id, @QueryParam("reportOnDisk") String reportOnDisk) {
+    @Operation(summary = "Adds usage metrics from a SUSHI report",
+            description = "Parses a SUSHI report from disk, saves usage metrics for the specified dataset, and reports completion.")
+    public Response addUsageMetricsFromSushiReport(
+            @Parameter(description = "Dataset id or persistent identifier that receives the usage metrics.", required = true)
+            @PathParam("id") String id,
+            @Parameter(description = "Server-side path to the SUSHI report JSON file.", required = true)
+            @QueryParam("reportOnDisk") String reportOnDisk) {
 
         try {
             JsonObject report = JsonUtil.getJsonObjectFromFile(reportOnDisk);
@@ -119,7 +131,11 @@ public Response addUsageMetricsFromSushiReport(@PathParam("id") String id, @Quer
 
     @POST
     @Path("/addUsageMetricsFromSushiReport")
-    public Response addUsageMetricsFromSushiReportAll(@QueryParam("reportOnDisk") String reportOnDisk) {
+    @Operation(summary = "Adds usage metrics from a SUSHI report for all datasets",
+            description = "Parses a SUSHI report from disk, saves usage metrics for all datasets represented in the report, and reports completion.")
+    public Response addUsageMetricsFromSushiReportAll(
+            @Parameter(description = "Server-side path to the SUSHI report JSON file.", required = true)
+            @QueryParam("reportOnDisk") String reportOnDisk) {
 
         try {
             JsonObject report = JsonUtil.getJsonObjectFromFile(reportOnDisk);
@@ -141,7 +157,11 @@ public Response addUsageMetricsFromSushiReportAll(@QueryParam("reportOnDisk") St
 
     @POST
     @Path("{id}/updateCitationsForDataset")
-    public Response updateCitationsForDataset(@PathParam("id") String id) {
+    @Operation(summary = "Queues citation updates for a dataset",
+            description = "Validates that the dataset uses a DataCite DOI provider and queues a background citation update from DataCite EventData.")
+    public Response updateCitationsForDataset(
+            @Parameter(description = "Dataset id or persistent identifier whose citation metrics are updated.", required = true)
+            @PathParam("id") String id) {
         try {
             // First validate that the dataset exists and has a valid DOI
             final Dataset dataset = findDatasetOrDie(id);
@@ -327,7 +347,11 @@ private boolean processCitationUpdate(Dataset dataset, GlobalId pid, PidProvider
     
     @GET
     @Path("{yearMonth}/processingState")
-    public Response getProcessingState(@PathParam("yearMonth") String yearMonth) {
+    @Operation(summary = "Returns Make Data Count processing state",
+            description = "Returns the processing state, state-change timestamp, and server for the specified year and month.")
+    public Response getProcessingState(
+            @Parameter(description = "Year and month for the processing state, formatted as YYYY-MM.", required = true)
+            @PathParam("yearMonth") String yearMonth) {
         MakeDataCountProcessState mdcps;
         try {
             mdcps = makeDataCountProcessStateService.getMakeDataCountProcessState(yearMonth);
@@ -350,7 +374,15 @@ public Response getProcessingState(@PathParam("yearMonth") String yearMonth) {
 
     @POST
     @Path("{yearMonth}/processingState")
-    public Response updateProcessingState(@PathParam("yearMonth") String yearMonth, @QueryParam("state") String state, @QueryParam("server") String server) {
+    @Operation(summary = "Sets Make Data Count processing state",
+            description = "Creates or updates the processing state for the specified year and month.")
+    public Response updateProcessingState(
+            @Parameter(description = "Year and month for the processing state, formatted as YYYY-MM.", required = true)
+            @PathParam("yearMonth") String yearMonth,
+            @Parameter(description = "Processing state value to store.", required = true)
+            @QueryParam("state") String state,
+            @Parameter(description = "Server name associated with the processing state.")
+            @QueryParam("server") String server) {
         MakeDataCountProcessState mdcps;
         try {
             mdcps = makeDataCountProcessStateService.setMakeDataCountProcessState(yearMonth, state, server);
@@ -370,7 +402,11 @@ public Response updateProcessingState(@PathParam("yearMonth") String yearMonth,
 
     @DELETE
     @Path("{yearMonth}/processingState")
-    public Response deleteProcessingState(@PathParam("yearMonth") String yearMonth) {
+    @Operation(summary = "Deletes Make Data Count processing state",
+            description = "Deletes the processing state for the specified year and month.")
+    public Response deleteProcessingState(
+            @Parameter(description = "Year and month for the processing state, formatted as YYYY-MM.", required = true)
+            @PathParam("yearMonth") String yearMonth) {
         boolean deleted = makeDataCountProcessStateService.deleteMakeDataCountProcessState(yearMonth);
         if (deleted) {
             return ok("Processing State deleted for " + yearMonth);
diff --git a/src/main/java/edu/harvard/iq/dataverse/api/Metadata.java b/src/main/java/edu/harvard/iq/dataverse/api/Metadata.java
index 8d63d25cfd3..b57dc18412c 100644
--- a/src/main/java/edu/harvard/iq/dataverse/api/Metadata.java
+++ b/src/main/java/edu/harvard/iq/dataverse/api/Metadata.java
@@ -17,6 +17,9 @@
 
 import edu.harvard.iq.dataverse.harvest.server.OAISetServiceBean;
 import edu.harvard.iq.dataverse.harvest.server.OAISet;
+import org.eclipse.microprofile.openapi.annotations.Operation;
+import org.eclipse.microprofile.openapi.annotations.parameters.Parameter;
+import org.eclipse.microprofile.openapi.annotations.tags.Tag;
 
 /**
  *
@@ -25,6 +28,7 @@
  */
 
 @Path("admin/metadata")
+@Tag(name = "Admin", description = "Administrative Dataverse operations.")
 public class Metadata extends AbstractApiBean {
     private static final Logger logger = Logger.getLogger(Metadata.class.getName());
 
@@ -45,6 +49,8 @@ public class Metadata extends AbstractApiBean {
     @GET
     @Path("/exportAll")
     @Produces("application/json")
+    @Operation(summary = "Starts metadata export jobs",
+            description = "Starts background exports for published local datasets that have not been exported since their last publication.")
     public Response exportAll() {
         datasetService.exportAllAsync();
         return this.accepted();
@@ -55,7 +61,11 @@ public Response exportAll() {
     @GET
     @Path("/reExportAll")
     @Produces("application/json")
-    public Response reExportAll(@QueryParam(value = "olderThan") String olderThan) {
+    @Operation(summary = "Starts metadata re-export jobs",
+            description = "Starts background re-export jobs for published local datasets, optionally limited to datasets older than a supplied date.")
+    public Response reExportAll(
+            @Parameter(description = "Optional cutoff date in YYYY-MM-DD format for selecting datasets to re-export.")
+            @QueryParam(value = "olderThan") String olderThan) {
         Date reExportDate = null;
         if (olderThan != null && !olderThan.isEmpty()) {
             try {
@@ -72,7 +82,11 @@ public Response reExportAll(@QueryParam(value = "olderThan") String olderThan) {
 
     @GET
     @Path("{id}/reExportDataset")
-    public Response indexDatasetByPersistentId(@PathParam("id") String id) {
+    @Operation(summary = "Starts a dataset metadata re-export",
+            description = "Starts a background metadata re-export for the specified dataset.")
+    public Response indexDatasetByPersistentId(
+            @Parameter(description = "Dataset id or persistent identifier to re-export.", required = true)
+            @PathParam("id") String id) {
         try {
             Dataset dataset = findDatasetOrDie(id);
             datasetService.reExportDatasetAsync(dataset);
@@ -84,6 +98,8 @@ public Response indexDatasetByPersistentId(@PathParam("id") String id) {
 
     @GET
     @Path("clearExportTimestamps")
+    @Operation(summary = "Clears metadata export timestamps",
+            description = "Clears stored metadata export timestamps for all datasets without deleting cached metadata export files.")
     public Response clearExportTimestamps() {
         // only clear the timestamp in the database, cached metadata export files are not deleted
         int numItemsCleared = datasetService.clearAllExportTimes();
@@ -96,7 +112,11 @@ public Response clearExportTimestamps() {
      */
     @PUT
     @Path("/exportOAI/{specname}")
-    public Response exportOaiSet( @PathParam("specname") String spec )
+    @Operation(summary = "Starts an OAI set export",
+            description = "Marks the specified OAI set as updating and starts its metadata export in the background.")
+    public Response exportOaiSet(
+            @Parameter(description = "OAI set specification name to export.", required = true)
+            @PathParam("specname") String spec)
     {
 	    // assuming this belongs here (because it's a metadata export), but open to moving it elsewhere
 	    OAISet set = null;
diff --git a/src/main/java/edu/harvard/iq/dataverse/api/MetadataBlocks.java b/src/main/java/edu/harvard/iq/dataverse/api/MetadataBlocks.java
index 8861abd4803..8bf208c6de5 100644
--- a/src/main/java/edu/harvard/iq/dataverse/api/MetadataBlocks.java
+++ b/src/main/java/edu/harvard/iq/dataverse/api/MetadataBlocks.java
@@ -3,6 +3,9 @@
 import edu.harvard.iq.dataverse.MetadataBlock;
 import jakarta.ws.rs.*;
 import jakarta.ws.rs.core.Response;
+import org.eclipse.microprofile.openapi.annotations.Operation;
+import org.eclipse.microprofile.openapi.annotations.parameters.Parameter;
+import org.eclipse.microprofile.openapi.annotations.tags.Tag;
 
 import java.util.List;
 
@@ -15,18 +18,28 @@
  */
 @Path("metadatablocks")
 @Produces("application/json")
+@Tag(name = "Metadata", description = "Metadata block and metadata export operations.")
 public class MetadataBlocks extends AbstractApiBean {
 
     @GET
-    public Response listMetadataBlocks(@QueryParam("onlyDisplayedOnCreate") boolean onlyDisplayedOnCreate,
-                                       @QueryParam("returnDatasetFieldTypes") boolean returnDatasetFieldTypes) {
+    @Operation(summary = "Lists metadata blocks",
+            description = "Returns metadata blocks as JSON, optionally limited to blocks displayed during dataset creation and optionally including dataset field types.")
+    public Response listMetadataBlocks(
+            @Parameter(description = "Limit results to metadata blocks displayed during dataset creation.")
+            @QueryParam("onlyDisplayedOnCreate") boolean onlyDisplayedOnCreate,
+            @Parameter(description = "Include dataset field type definitions in each metadata block.")
+            @QueryParam("returnDatasetFieldTypes") boolean returnDatasetFieldTypes) {
         List<MetadataBlock> metadataBlocks = metadataBlockSvc.listMetadataBlocks(onlyDisplayedOnCreate);
         return ok(json(metadataBlocks, returnDatasetFieldTypes, onlyDisplayedOnCreate));
     }
 
     @Path("{identifier}")
     @GET
-    public Response getMetadataBlock(@PathParam("identifier") String idtf) {
+    @Operation(summary = "Returns a metadata block",
+            description = "Returns the metadata block identified by id, name, or display name.")
+    public Response getMetadataBlock(
+            @Parameter(description = "Metadata block id, name, or display name.", required = true)
+            @PathParam("identifier") String idtf) {
         MetadataBlock b = findMetadataBlock(idtf);
         return (b != null) ? ok(json(b)) : notFound("Can't find metadata block '" + idtf + "'");
     }
diff --git a/src/main/java/edu/harvard/iq/dataverse/api/Metrics.java b/src/main/java/edu/harvard/iq/dataverse/api/Metrics.java
index 74bc4184099..5cece335f5c 100644
--- a/src/main/java/edu/harvard/iq/dataverse/api/Metrics.java
+++ b/src/main/java/edu/harvard/iq/dataverse/api/Metrics.java
@@ -28,6 +28,9 @@
 import static jakarta.ws.rs.core.Response.Status.BAD_REQUEST;
 import jakarta.ws.rs.core.UriInfo;
 import jakarta.ws.rs.core.Variant;
+import org.eclipse.microprofile.openapi.annotations.Operation;
+import org.eclipse.microprofile.openapi.annotations.parameters.Parameter;
+import org.eclipse.microprofile.openapi.annotations.tags.Tag;
 
 /**
  * API endpoints for various metrics.
@@ -40,6 +43,7 @@
  * @author pdurbin, madunlap
  */
 @Path("info/metrics")
+@Tag(name = "Info", description = "General information about the Dataverse installation.")
 public class Metrics extends AbstractApiBean {
     private static final Logger logger = Logger.getLogger(Metrics.class.getName());
 
@@ -47,14 +51,22 @@ public class Metrics extends AbstractApiBean {
 
     @GET
     @Path("dataverses")
-    public Response getDataversesAllTime(@Context UriInfo uriInfo, @QueryParam("parentAlias") String parentAlias) {
+    @Operation(summary = "Calculates total dataverse count",
+            description = "Calculates the number of released dataverses through the current month, optionally scoped to a released parent dataverse.")
+    public Response getDataversesAllTime(@Context UriInfo uriInfo,
+            @Parameter(description = "Alias of a released parent dataverse used to scope the metric.")
+            @QueryParam("parentAlias") String parentAlias) {
         return getDataversesToMonth(uriInfo, MetricsUtil.getCurrentMonth(), parentAlias);
     }
 
     @GET
     @Path("dataverses/monthly")
     @Produces("text/csv, application/json")
-    public Response getDataversesTimeSeries(@Context Request req, @Context UriInfo uriInfo, @QueryParam("parentAlias") String parentAlias) {
+    @Operation(summary = "Calculates monthly dataverse counts",
+            description = "Calculates a monthly time series of released dataverse counts as JSON or CSV, optionally scoped to a released parent dataverse.")
+    public Response getDataversesTimeSeries(@Context Request req, @Context UriInfo uriInfo,
+            @Parameter(description = "Alias of a released parent dataverse used to scope the metric.")
+            @QueryParam("parentAlias") String parentAlias) {
         Dataverse d = findDataverseOrDieIfNotFound(parentAlias);
 
         try {
@@ -79,7 +91,13 @@ public Response getDataversesTimeSeries(@Context Request req, @Context UriInfo u
 
     @GET
     @Path("dataverses/toMonth/{yyyymm}")
-    public Response getDataversesToMonth(@Context UriInfo uriInfo, @PathParam("yyyymm") String yyyymm, @QueryParam("parentAlias") String parentAlias) {
+    @Operation(summary = "Calculates dataverse count through a month",
+            description = "Calculates the number of released dataverses through the specified month, optionally scoped to a released parent dataverse.")
+    public Response getDataversesToMonth(@Context UriInfo uriInfo,
+            @Parameter(description = "Year and month cutoff for the metric, formatted as YYYYMM.", required = true)
+            @PathParam("yyyymm") String yyyymm,
+            @Parameter(description = "Alias of a released parent dataverse used to scope the metric.")
+            @QueryParam("parentAlias") String parentAlias) {
         Dataverse d = findDataverseOrDieIfNotFound(parentAlias);
 
         try {
@@ -105,7 +123,13 @@ public Response getDataversesToMonth(@Context UriInfo uriInfo, @PathParam("yyyym
 
     @GET
     @Path("dataverses/pastDays/{days}")
-    public Response getDataversesPastDays(@Context UriInfo uriInfo, @PathParam("days") int days, @QueryParam("parentAlias") String parentAlias) {
+    @Operation(summary = "Calculates recent dataverse count",
+            description = "Calculates the number of released dataverses created during the specified number of past days, optionally scoped to a released parent dataverse.")
+    public Response getDataversesPastDays(@Context UriInfo uriInfo,
+            @Parameter(description = "Positive number of past days included in the metric.", required = true)
+            @PathParam("days") int days,
+            @Parameter(description = "Alias of a released parent dataverse used to scope the metric.")
+            @QueryParam("parentAlias") String parentAlias) {
         Dataverse d = findDataverseOrDieIfNotFound(parentAlias);
 
         try {
@@ -134,7 +158,11 @@ public Response getDataversesPastDays(@Context UriInfo uriInfo, @PathParam("days
     @GET
     @Path("dataverses/byCategory")
     @Produces("text/csv, application/json")
-    public Response getDataversesByCategory(@Context Request req, @Context UriInfo uriInfo, @QueryParam("parentAlias") String parentAlias) {
+    @Operation(summary = "Calculates dataverse counts by category",
+            description = "Calculates released dataverse counts grouped by dataverse category as JSON or CSV, optionally scoped to a released parent dataverse.")
+    public Response getDataversesByCategory(@Context Request req, @Context UriInfo uriInfo,
+            @Parameter(description = "Alias of a released parent dataverse used to scope the metric.")
+            @QueryParam("parentAlias") String parentAlias) {
         Dataverse d = findDataverseOrDieIfNotFound(parentAlias);
 
         try {
@@ -161,7 +189,11 @@ public Response getDataversesByCategory(@Context Request req, @Context UriInfo u
     @GET
     @Path("dataverses/bySubject")
     @Produces("text/csv, application/json")
-    public Response getDataversesBySubject(@Context Request req, @Context UriInfo uriInfo, @QueryParam("parentAlias") String parentAlias) {
+    @Operation(summary = "Calculates dataverse counts by subject",
+            description = "Calculates released dataverse counts grouped by subject as JSON or CSV, optionally scoped to a released parent dataverse.")
+    public Response getDataversesBySubject(@Context Request req, @Context UriInfo uriInfo,
+            @Parameter(description = "Alias of a released parent dataverse used to scope the metric.")
+            @QueryParam("parentAlias") String parentAlias) {
         Dataverse d = findDataverseOrDieIfNotFound(parentAlias);
 
         try {
@@ -190,14 +222,26 @@ public Response getDataversesBySubject(@Context Request req, @Context UriInfo ur
 
     @GET
     @Path("datasets")
-    public Response getDatasetsAllTime(@Context UriInfo uriInfo, @QueryParam("dataLocation") String dataLocation, @QueryParam("parentAlias") String parentAlias) {
+    @Operation(summary = "Calculates total dataset count",
+            description = "Calculates the number of released datasets through the current month, optionally filtered by storage location and parent dataverse.")
+    public Response getDatasetsAllTime(@Context UriInfo uriInfo,
+            @Parameter(description = "Storage location filter for the dataset metric.")
+            @QueryParam("dataLocation") String dataLocation,
+            @Parameter(description = "Alias of a released parent dataverse used to scope the metric.")
+            @QueryParam("parentAlias") String parentAlias) {
         return getDatasetsToMonth(uriInfo, MetricsUtil.getCurrentMonth(), dataLocation, parentAlias);
     }
 
     @GET
     @Path("datasets/monthly")
     @Produces("text/csv, application/json")
-    public Response getDatasetsTimeSeriest(@Context Request req, @Context UriInfo uriInfo, @QueryParam("dataLocation") String dataLocation, @QueryParam("parentAlias") String parentAlias) {
+    @Operation(summary = "Calculates monthly dataset counts",
+            description = "Calculates a monthly time series of released dataset counts as JSON or CSV, optionally filtered by storage location and parent dataverse.")
+    public Response getDatasetsTimeSeriest(@Context Request req, @Context UriInfo uriInfo,
+            @Parameter(description = "Storage location filter for the dataset metric.")
+            @QueryParam("dataLocation") String dataLocation,
+            @Parameter(description = "Alias of a released parent dataverse used to scope the metric.")
+            @QueryParam("parentAlias") String parentAlias) {
 
         Dataverse d = findDataverseOrDieIfNotFound(parentAlias);
         try {
@@ -223,7 +267,15 @@ public Response getDatasetsTimeSeriest(@Context Request req, @Context UriInfo ur
 
     @GET
     @Path("datasets/toMonth/{yyyymm}")
-    public Response getDatasetsToMonth(@Context UriInfo uriInfo, @PathParam("yyyymm") String yyyymm, @QueryParam("dataLocation") String dataLocation, @QueryParam("parentAlias") String parentAlias) {
+    @Operation(summary = "Calculates dataset count through a month",
+            description = "Calculates the number of released datasets through the specified month, optionally filtered by storage location and parent dataverse.")
+    public Response getDatasetsToMonth(@Context UriInfo uriInfo,
+            @Parameter(description = "Year and month cutoff for the metric, formatted as YYYYMM.", required = true)
+            @PathParam("yyyymm") String yyyymm,
+            @Parameter(description = "Storage location filter for the dataset metric.")
+            @QueryParam("dataLocation") String dataLocation,
+            @Parameter(description = "Alias of a released parent dataverse used to scope the metric.")
+            @QueryParam("parentAlias") String parentAlias) {
         Dataverse d = findDataverseOrDieIfNotFound(parentAlias);
 
         try {
@@ -250,7 +302,15 @@ public Response getDatasetsToMonth(@Context UriInfo uriInfo, @PathParam("yyyymm"
 
     @GET
     @Path("datasets/pastDays/{days}")
-    public Response getDatasetsPastDays(@Context UriInfo uriInfo, @PathParam("days") int days, @QueryParam("dataLocation") String dataLocation, @QueryParam("parentAlias") String parentAlias) {
+    @Operation(summary = "Calculates recent dataset count",
+            description = "Calculates the number of released datasets created during the specified number of past days, optionally filtered by storage location and parent dataverse.")
+    public Response getDatasetsPastDays(@Context UriInfo uriInfo,
+            @Parameter(description = "Positive number of past days included in the metric.", required = true)
+            @PathParam("days") int days,
+            @Parameter(description = "Storage location filter for the dataset metric.")
+            @QueryParam("dataLocation") String dataLocation,
+            @Parameter(description = "Alias of a released parent dataverse used to scope the metric.")
+            @QueryParam("parentAlias") String parentAlias) {
         Dataverse d = findDataverseOrDieIfNotFound(parentAlias);
 
         try {
@@ -280,14 +340,28 @@ public Response getDatasetsPastDays(@Context UriInfo uriInfo, @PathParam("days")
     @GET
     @Path("datasets/bySubject")
     @Produces("text/csv, application/json")
-    public Response getDatasetsBySubject(@Context Request req, @Context UriInfo uriInfo, @QueryParam("dataLocation") String dataLocation, @QueryParam("parentAlias") String parentAlias) {
+    @Operation(summary = "Calculates dataset counts by subject",
+            description = "Calculates released dataset counts grouped by subject through the current month as JSON or CSV, optionally filtered by storage location and parent dataverse.")
+    public Response getDatasetsBySubject(@Context Request req, @Context UriInfo uriInfo,
+            @Parameter(description = "Storage location filter for the dataset metric.")
+            @QueryParam("dataLocation") String dataLocation,
+            @Parameter(description = "Alias of a released parent dataverse used to scope the metric.")
+            @QueryParam("parentAlias") String parentAlias) {
         return getDatasetsBySubjectToMonth(req, uriInfo, MetricsUtil.getCurrentMonth(), dataLocation, parentAlias);
     }
 
     @GET
     @Path("datasets/bySubject/toMonth/{yyyymm}")
     @Produces("text/csv, application/json")
-    public Response getDatasetsBySubjectToMonth(@Context Request req, @Context UriInfo uriInfo, @PathParam("yyyymm") String yyyymm, @QueryParam("dataLocation") String dataLocation, @QueryParam("parentAlias") String parentAlias) {
+    @Operation(summary = "Calculates dataset counts by subject through a month",
+            description = "Calculates released dataset counts grouped by subject through the specified month as JSON or CSV, optionally filtered by storage location and parent dataverse.")
+    public Response getDatasetsBySubjectToMonth(@Context Request req, @Context UriInfo uriInfo,
+            @Parameter(description = "Year and month cutoff for the metric, formatted as YYYYMM.", required = true)
+            @PathParam("yyyymm") String yyyymm,
+            @Parameter(description = "Storage location filter for the dataset metric.")
+            @QueryParam("dataLocation") String dataLocation,
+            @Parameter(description = "Alias of a released parent dataverse used to scope the metric.")
+            @QueryParam("parentAlias") String parentAlias) {
         Dataverse d = findDataverseOrDieIfNotFound(parentAlias);
 
         try {
@@ -316,14 +390,22 @@ public Response getDatasetsBySubjectToMonth(@Context Request req, @Context UriIn
     /** Files */
     @GET
     @Path("files")
-    public Response getFilesAllTime(@Context UriInfo uriInfo, @QueryParam("parentAlias") String parentAlias) {
+    @Operation(summary = "Calculates total file count",
+            description = "Calculates the number of released files through the current month, optionally scoped to a released parent dataverse.")
+    public Response getFilesAllTime(@Context UriInfo uriInfo,
+            @Parameter(description = "Alias of a released parent dataverse used to scope the metric.")
+            @QueryParam("parentAlias") String parentAlias) {
         return getFilesToMonth(uriInfo, MetricsUtil.getCurrentMonth(), parentAlias);
     }
 
     @GET
     @Path("files/monthly")
     @Produces("text/csv, application/json")
-    public Response getFilesTimeSeries(@Context Request req, @Context UriInfo uriInfo, @QueryParam("parentAlias") String parentAlias) {
+    @Operation(summary = "Calculates monthly file counts",
+            description = "Calculates a monthly time series of released file counts as JSON or CSV, optionally scoped to a released parent dataverse.")
+    public Response getFilesTimeSeries(@Context Request req, @Context UriInfo uriInfo,
+            @Parameter(description = "Alias of a released parent dataverse used to scope the metric.")
+            @QueryParam("parentAlias") String parentAlias) {
         Dataverse d = findDataverseOrDieIfNotFound(parentAlias);
         try {
             errorIfUnrecongizedQueryParamPassed(uriInfo, new String[] { "parentAlias" });
@@ -348,7 +430,13 @@ public Response getFilesTimeSeries(@Context Request req, @Context UriInfo uriInf
 
     @GET
     @Path("files/toMonth/{yyyymm}")
-    public Response getFilesToMonth(@Context UriInfo uriInfo, @PathParam("yyyymm") String yyyymm, @QueryParam("parentAlias") String parentAlias) {
+    @Operation(summary = "Calculates file count through a month",
+            description = "Calculates the number of released files through the specified month, optionally scoped to a released parent dataverse.")
+    public Response getFilesToMonth(@Context UriInfo uriInfo,
+            @Parameter(description = "Year and month cutoff for the metric, formatted as YYYYMM.", required = true)
+            @PathParam("yyyymm") String yyyymm,
+            @Parameter(description = "Alias of a released parent dataverse used to scope the metric.")
+            @QueryParam("parentAlias") String parentAlias) {
         Dataverse d = findDataverseOrDieIfNotFound(parentAlias);
 
         try {
@@ -376,7 +464,13 @@ public Response getFilesToMonth(@Context UriInfo uriInfo, @PathParam("yyyymm") S
 
     @GET
     @Path("files/pastDays/{days}")
-    public Response getFilesPastDays(@Context UriInfo uriInfo, @PathParam("days") int days, @QueryParam("parentAlias") String parentAlias) {
+    @Operation(summary = "Calculates recent file count",
+            description = "Calculates the number of released files created during the specified number of past days, optionally scoped to a released parent dataverse.")
+    public Response getFilesPastDays(@Context UriInfo uriInfo,
+            @Parameter(description = "Positive number of past days included in the metric.", required = true)
+            @PathParam("days") int days,
+            @Parameter(description = "Alias of a released parent dataverse used to scope the metric.")
+            @QueryParam("parentAlias") String parentAlias) {
         Dataverse d = findDataverseOrDieIfNotFound(parentAlias);
 
         try {
@@ -406,7 +500,11 @@ public Response getFilesPastDays(@Context UriInfo uriInfo, @PathParam("days") in
     @GET
     @Path("/files/byType/monthly")
     @Produces("text/csv, application/json")
-    public Response getFilesByTypeTimeSeries(@Context Request req, @Context UriInfo uriInfo, @QueryParam("parentAlias") String parentAlias) {
+    @Operation(summary = "Calculates monthly file counts by type",
+            description = "Calculates a monthly time series of released file counts and sizes grouped by content type as JSON or CSV, optionally scoped to a released parent dataverse.")
+    public Response getFilesByTypeTimeSeries(@Context Request req, @Context UriInfo uriInfo,
+            @Parameter(description = "Alias of a released parent dataverse used to scope the metric.")
+            @QueryParam("parentAlias") String parentAlias) {
         Dataverse d = findDataverseOrDieIfNotFound(parentAlias);
         try {
             errorIfUnrecongizedQueryParamPassed(uriInfo, new String[] { "parentAlias" });
@@ -432,7 +530,11 @@ public Response getFilesByTypeTimeSeries(@Context Request req, @Context UriInfo
     @GET
     @Path("/files/byType")
     @Produces("text/csv, application/json")
-    public Response getFilesByType(@Context Request req, @Context UriInfo uriInfo, @QueryParam("parentAlias") String parentAlias) {
+    @Operation(summary = "Calculates file counts by type",
+            description = "Calculates released file counts and sizes grouped by content type as JSON or CSV, optionally scoped to a released parent dataverse.")
+    public Response getFilesByType(@Context Request req, @Context UriInfo uriInfo,
+            @Parameter(description = "Alias of a released parent dataverse used to scope the metric.")
+            @QueryParam("parentAlias") String parentAlias) {
         Dataverse d = findDataverseOrDieIfNotFound(parentAlias);
         try {
             errorIfUnrecongizedQueryParamPassed(uriInfo, new String[] { "parentAlias" });
@@ -460,14 +562,22 @@ public Response getFilesByType(@Context Request req, @Context UriInfo uriInfo, @
 
     @GET
     @Path("downloads")
-    public Response getDownloadsAllTime(@Context UriInfo uriInfo, @QueryParam("parentAlias") String parentAlias) {
+    @Operation(summary = "Calculates total download count",
+            description = "Calculates the number of file downloads through the current month, optionally scoped to a released parent dataverse.")
+    public Response getDownloadsAllTime(@Context UriInfo uriInfo,
+            @Parameter(description = "Alias of a released parent dataverse used to scope the metric.")
+            @QueryParam("parentAlias") String parentAlias) {
         return getDownloadsToMonth(uriInfo, MetricsUtil.getCurrentMonth(), parentAlias);
     }
 
     @GET
     @Path("downloads/monthly")
     @Produces("text/csv, application/json")
-    public Response getDownloadsTimeSeries(@Context Request req, @Context UriInfo uriInfo, @QueryParam("parentAlias") String parentAlias) {
+    @Operation(summary = "Calculates monthly download counts",
+            description = "Calculates a monthly time series of file download counts as JSON or CSV, optionally scoped to a released parent dataverse.")
+    public Response getDownloadsTimeSeries(@Context Request req, @Context UriInfo uriInfo,
+            @Parameter(description = "Alias of a released parent dataverse used to scope the metric.")
+            @QueryParam("parentAlias") String parentAlias) {
         Dataverse d = findDataverseOrDieIfNotFound(parentAlias);
         try {
             errorIfUnrecongizedQueryParamPassed(uriInfo, new String[] { "parentAlias" });
@@ -493,7 +603,13 @@ public Response getDownloadsTimeSeries(@Context Request req, @Context UriInfo ur
 
     @GET
     @Path("downloads/toMonth/{yyyymm}")
-    public Response getDownloadsToMonth(@Context UriInfo uriInfo, @PathParam("yyyymm") String yyyymm, @QueryParam("parentAlias") String parentAlias) {
+    @Operation(summary = "Calculates download count through a month",
+            description = "Calculates the number of file downloads through the specified month, optionally scoped to a released parent dataverse.")
+    public Response getDownloadsToMonth(@Context UriInfo uriInfo,
+            @Parameter(description = "Year and month cutoff for the metric, formatted as YYYYMM.", required = true)
+            @PathParam("yyyymm") String yyyymm,
+            @Parameter(description = "Alias of a released parent dataverse used to scope the metric.")
+            @QueryParam("parentAlias") String parentAlias) {
         Dataverse d = findDataverseOrDieIfNotFound(parentAlias);
 
         try {
@@ -523,7 +639,13 @@ public Response getDownloadsToMonth(@Context UriInfo uriInfo, @PathParam("yyyymm
 
     @GET
     @Path("downloads/pastDays/{days}")
-    public Response getDownloadsPastDays(@Context UriInfo uriInfo, @PathParam("days") int days, @QueryParam("parentAlias") String parentAlias) {
+    @Operation(summary = "Calculates recent download count",
+            description = "Calculates the number of file downloads during the specified number of past days, optionally scoped to a released parent dataverse.")
+    public Response getDownloadsPastDays(@Context UriInfo uriInfo,
+            @Parameter(description = "Positive number of past days included in the metric.", required = true)
+            @PathParam("days") int days,
+            @Parameter(description = "Alias of a released parent dataverse used to scope the metric.")
+            @QueryParam("parentAlias") String parentAlias) {
         Dataverse d = findDataverseOrDieIfNotFound(parentAlias);
 
         try {
@@ -552,13 +674,19 @@ public Response getDownloadsPastDays(@Context UriInfo uriInfo, @PathParam("days"
 
     @GET
     @Path("accounts")
+    @Operation(summary = "Calculates total account count",
+            description = "Calculates the number of user accounts through the current month.")
     public Response getAccountsAllTime(@Context UriInfo uriInfo) {
         return getAccountsToMonth(uriInfo, MetricsUtil.getCurrentMonth());
     }
 
     @GET
     @Path("accounts/toMonth/{yyyymm}")
-    public Response getAccountsToMonth(@Context UriInfo uriInfo, @PathParam("yyyymm") String yyyymm) {
+    @Operation(summary = "Calculates account count through a month",
+            description = "Calculates the number of user accounts through the specified month.")
+    public Response getAccountsToMonth(@Context UriInfo uriInfo,
+            @Parameter(description = "Year and month cutoff for the metric, formatted as YYYYMM.", required = true)
+            @PathParam("yyyymm") String yyyymm) {
 
         try {
             errorIfUnrecongizedQueryParamPassed(uriInfo, new String[] { });
@@ -586,7 +714,11 @@ public Response getAccountsToMonth(@Context UriInfo uriInfo, @PathParam("yyyymm"
 
     @GET
     @Path("accounts/pastDays/{days}")
-    public Response getAccountsPastDays(@Context UriInfo uriInfo, @PathParam("days") int days) {
+    @Operation(summary = "Calculates recent account count",
+            description = "Calculates the number of user accounts created during the specified number of past days.")
+    public Response getAccountsPastDays(@Context UriInfo uriInfo,
+            @Parameter(description = "Positive number of past days included in the metric.", required = true)
+            @PathParam("days") int days) {
 
         try {
             errorIfUnrecongizedQueryParamPassed(uriInfo, new String[] { });
@@ -614,6 +746,8 @@ public Response getAccountsPastDays(@Context UriInfo uriInfo, @PathParam("days")
     @GET
     @Path("accounts/monthly")
     @Produces("text/csv, application/json")
+    @Operation(summary = "Calculates monthly account counts",
+            description = "Calculates a monthly time series of user account counts as JSON or CSV.")
     public Response getAccountsTimeSeries(@Context Request req, @Context UriInfo uriInfo) {
 
         try {
@@ -642,14 +776,30 @@ public Response getAccountsTimeSeries(@Context Request req, @Context UriInfo uri
 
     @GET
     @Path("makeDataCount/{metric}")
-    public Response getMakeDataCountMetricCurrentMonth(@Context UriInfo uriInfo, @PathParam("metric") String metricSupplied, @QueryParam("country") String country, @QueryParam("parentAlias") String parentAlias) {
+    @Operation(summary = "Calculates a Make Data Count metric",
+            description = "Calculates the requested Make Data Count metric through the current month, optionally filtered by country and parent dataverse.")
+    public Response getMakeDataCountMetricCurrentMonth(@Context UriInfo uriInfo,
+            @Parameter(description = "Make Data Count metric name to return.", required = true)
+            @PathParam("metric") String metricSupplied,
+            @Parameter(description = "ISO country code used to filter the metric.")
+            @QueryParam("country") String country,
+            @Parameter(description = "Alias of a released parent dataverse used to scope the metric.")
+            @QueryParam("parentAlias") String parentAlias) {
         return getMakeDataCountMetricToMonth(uriInfo, metricSupplied, MetricsUtil.getCurrentMonth(), country, parentAlias);
     }
 
     @GET
     @Path("makeDataCount/{metric}/monthly")
     @Produces("text/csv, application/json")
-    public Response getMakeDataCountMetricTimeSeries(@Context Request req, @Context UriInfo uriInfo, @PathParam("metric") String metricSupplied, @QueryParam("country") String country, @QueryParam("parentAlias") String parentAlias) {
+    @Operation(summary = "Calculates monthly Make Data Count metrics",
+            description = "Calculates a monthly time series for the requested Make Data Count metric as JSON or CSV, optionally filtered by country and parent dataverse.")
+    public Response getMakeDataCountMetricTimeSeries(@Context Request req, @Context UriInfo uriInfo,
+            @Parameter(description = "Make Data Count metric name to return.", required = true)
+            @PathParam("metric") String metricSupplied,
+            @Parameter(description = "ISO country code used to filter the metric.")
+            @QueryParam("country") String country,
+            @Parameter(description = "Alias of a released parent dataverse used to scope the metric.")
+            @QueryParam("parentAlias") String parentAlias) {
         Dataverse d = findDataverseOrDieIfNotFound(parentAlias);
         MakeDataCountUtil.MetricType metricType = null;
         try {
@@ -687,7 +837,17 @@ public Response getMakeDataCountMetricTimeSeries(@Context Request req, @Context
 
     @GET
     @Path("makeDataCount/{metric}/toMonth/{yyyymm}")
-    public Response getMakeDataCountMetricToMonth(@Context UriInfo uriInfo, @PathParam("metric") String metricSupplied, @PathParam("yyyymm") String yyyymm, @QueryParam("country") String country, @QueryParam("parentAlias") String parentAlias) {
+    @Operation(summary = "Calculates a Make Data Count metric through a month",
+            description = "Calculates the requested Make Data Count metric through the specified month, optionally filtered by country and parent dataverse.")
+    public Response getMakeDataCountMetricToMonth(@Context UriInfo uriInfo,
+            @Parameter(description = "Make Data Count metric name to return.", required = true)
+            @PathParam("metric") String metricSupplied,
+            @Parameter(description = "Year and month cutoff for the metric, formatted as YYYYMM.", required = true)
+            @PathParam("yyyymm") String yyyymm,
+            @Parameter(description = "ISO country code used to filter the metric.")
+            @QueryParam("country") String country,
+            @Parameter(description = "Alias of a released parent dataverse used to scope the metric.")
+            @QueryParam("parentAlias") String parentAlias) {
         Dataverse d = findDataverseOrDieIfNotFound(parentAlias);
         MakeDataCountUtil.MetricType metricType = null;
         try {
@@ -727,14 +887,24 @@ public Response getMakeDataCountMetricToMonth(@Context UriInfo uriInfo, @PathPar
     @GET
     @Path("filedownloads")
     @Produces("text/csv, application/json")
-    public Response getFileDownloadsAllTime(@Context Request req, @Context UriInfo uriInfo, @QueryParam("parentAlias") String parentAlias) {
+    @Operation(summary = "Calculates file download counts",
+            description = "Calculates file download counts by file through the current month as JSON or CSV, optionally scoped to a released parent dataverse.")
+    public Response getFileDownloadsAllTime(@Context Request req, @Context UriInfo uriInfo,
+            @Parameter(description = "Alias of a released parent dataverse used to scope the metric.")
+            @QueryParam("parentAlias") String parentAlias) {
         return getFileDownloadsToMonth(req, uriInfo, MetricsUtil.getCurrentMonth(), parentAlias);
     }
     
     @GET
     @Path("filedownloads/toMonth/{yyyymm}")
     @Produces("text/csv, application/json")
-    public Response getFileDownloadsToMonth(@Context Request req, @Context UriInfo uriInfo, @PathParam("yyyymm") String yyyymm, @QueryParam("parentAlias") String parentAlias) {
+    @Operation(summary = "Calculates file download counts through a month",
+            description = "Calculates file download counts by file through the specified month as JSON or CSV, optionally scoped to a released parent dataverse.")
+    public Response getFileDownloadsToMonth(@Context Request req, @Context UriInfo uriInfo,
+            @Parameter(description = "Year and month cutoff for the metric, formatted as YYYYMM.", required = true)
+            @PathParam("yyyymm") String yyyymm,
+            @Parameter(description = "Alias of a released parent dataverse used to scope the metric.")
+            @QueryParam("parentAlias") String parentAlias) {
         Dataverse d = findDataverseOrDieIfNotFound(parentAlias);
 
         try {
@@ -762,7 +932,11 @@ public Response getFileDownloadsToMonth(@Context Request req, @Context UriInfo u
     @GET
     @Path("filedownloads/monthly")
     @Produces("text/csv, application/json")
-    public Response getFileDownloadsTimeSeries(@Context Request req, @Context UriInfo uriInfo, @QueryParam("parentAlias") String parentAlias) {
+    @Operation(summary = "Calculates monthly file download counts",
+            description = "Calculates a monthly time series of file download counts by file as JSON or CSV, optionally scoped to a released parent dataverse.")
+    public Response getFileDownloadsTimeSeries(@Context Request req, @Context UriInfo uriInfo,
+            @Parameter(description = "Alias of a released parent dataverse used to scope the metric.")
+            @QueryParam("parentAlias") String parentAlias) {
         Dataverse d = findDataverseOrDieIfNotFound(parentAlias);
         try {
             errorIfUnrecongizedQueryParamPassed(uriInfo, new String[] { "parentAlias" });
@@ -788,14 +962,22 @@ public Response getFileDownloadsTimeSeries(@Context Request req, @Context UriInf
     @GET
     @Path("uniquedownloads")
     @Produces("text/csv, application/json")
-    public Response getUniqueDownloadsAllTime(@Context Request req, @Context UriInfo uriInfo, @QueryParam("parentAlias") String parentAlias) {
+    @Operation(summary = "Calculates unique dataset download counts",
+            description = "Calculates unique dataset download counts through the current month as JSON or CSV, optionally scoped to a released parent dataverse.")
+    public Response getUniqueDownloadsAllTime(@Context Request req, @Context UriInfo uriInfo,
+            @Parameter(description = "Alias of a released parent dataverse used to scope the metric.")
+            @QueryParam("parentAlias") String parentAlias) {
         return getUniqueDownloadsToMonth(req, uriInfo, MetricsUtil.getCurrentMonth(), parentAlias);
     }
 
     @GET
     @Path("uniquedownloads/monthly")
     @Produces("text/csv, application/json")
-    public Response getUniqueDownloadsTimeSeries(@Context Request req, @Context UriInfo uriInfo, @QueryParam("parentAlias") String parentAlias) {
+    @Operation(summary = "Calculates monthly unique dataset download counts",
+            description = "Calculates a monthly time series of unique dataset download counts as JSON or CSV, optionally scoped to a released parent dataverse.")
+    public Response getUniqueDownloadsTimeSeries(@Context Request req, @Context UriInfo uriInfo,
+            @Parameter(description = "Alias of a released parent dataverse used to scope the metric.")
+            @QueryParam("parentAlias") String parentAlias) {
         Dataverse d = findDataverseOrDieIfNotFound(parentAlias);
         try {
             errorIfUnrecongizedQueryParamPassed(uriInfo, new String[] { "parentAlias" });
@@ -821,7 +1003,13 @@ public Response getUniqueDownloadsTimeSeries(@Context Request req, @Context UriI
     @GET
     @Path("uniquedownloads/toMonth/{yyyymm}")
     @Produces("text/csv, application/json")
-    public Response getUniqueDownloadsToMonth(@Context Request req, @Context UriInfo uriInfo, @PathParam("yyyymm") String yyyymm, @QueryParam("parentAlias") String parentAlias) {
+    @Operation(summary = "Calculates unique dataset download counts through a month",
+            description = "Calculates unique dataset download counts through the specified month as JSON or CSV, optionally scoped to a released parent dataverse.")
+    public Response getUniqueDownloadsToMonth(@Context Request req, @Context UriInfo uriInfo,
+            @Parameter(description = "Year and month cutoff for the metric, formatted as YYYYMM.", required = true)
+            @PathParam("yyyymm") String yyyymm,
+            @Parameter(description = "Alias of a released parent dataverse used to scope the metric.")
+            @QueryParam("parentAlias") String parentAlias) {
         Dataverse d = findDataverseOrDieIfNotFound(parentAlias);
 
         try {
@@ -849,14 +1037,24 @@ public Response getUniqueDownloadsToMonth(@Context Request req, @Context UriInfo
     @GET
     @Path("uniquefiledownloads")
     @Produces("text/csv, application/json")
-    public Response getUniqueFileDownloadsAllTime(@Context Request req, @Context UriInfo uriInfo, @QueryParam("parentAlias") String parentAlias) {
+    @Operation(summary = "Calculates unique file download counts",
+            description = "Calculates unique file download counts by file through the current month as JSON or CSV, optionally scoped to a released parent dataverse.")
+    public Response getUniqueFileDownloadsAllTime(@Context Request req, @Context UriInfo uriInfo,
+            @Parameter(description = "Alias of a released parent dataverse used to scope the metric.")
+            @QueryParam("parentAlias") String parentAlias) {
         return getUniqueFileDownloadsToMonth(req, uriInfo, MetricsUtil.getCurrentMonth(), parentAlias);
     }
     
     @GET
     @Path("uniquefiledownloads/toMonth/{yyyymm}")
     @Produces("text/csv, application/json")
-    public Response getUniqueFileDownloadsToMonth(@Context Request req, @Context UriInfo uriInfo, @PathParam("yyyymm") String yyyymm, @QueryParam("parentAlias") String parentAlias) {
+    @Operation(summary = "Calculates unique file download counts through a month",
+            description = "Calculates unique file download counts by file through the specified month as JSON or CSV, optionally scoped to a released parent dataverse.")
+    public Response getUniqueFileDownloadsToMonth(@Context Request req, @Context UriInfo uriInfo,
+            @Parameter(description = "Year and month cutoff for the metric, formatted as YYYYMM.", required = true)
+            @PathParam("yyyymm") String yyyymm,
+            @Parameter(description = "Alias of a released parent dataverse used to scope the metric.")
+            @QueryParam("parentAlias") String parentAlias) {
         Dataverse d = findDataverseOrDieIfNotFound(parentAlias);
 
         try {
@@ -884,7 +1082,11 @@ public Response getUniqueFileDownloadsToMonth(@Context Request req, @Context Uri
     @GET
     @Path("uniquefiledownloads/monthly")
     @Produces("text/csv, application/json")
-    public Response getUniqueFileDownloadsTimeSeries(@Context Request req, @Context UriInfo uriInfo, @QueryParam("parentAlias") String parentAlias) {
+    @Operation(summary = "Calculates monthly unique file download counts",
+            description = "Calculates a monthly time series of unique file download counts by file as JSON or CSV, optionally scoped to a released parent dataverse.")
+    public Response getUniqueFileDownloadsTimeSeries(@Context Request req, @Context UriInfo uriInfo,
+            @Parameter(description = "Alias of a released parent dataverse used to scope the metric.")
+            @QueryParam("parentAlias") String parentAlias) {
         Dataverse d = findDataverseOrDieIfNotFound(parentAlias);
         try {
             errorIfUnrecongizedQueryParamPassed(uriInfo, new String[] { "parentAlias" });
@@ -909,13 +1111,23 @@ public Response getUniqueFileDownloadsTimeSeries(@Context Request req, @Context
     
     @GET
     @Path("tree")
-    public Response getDataversesTree(@Context UriInfo uriInfo, @QueryParam("parentAlias") String parentAlias) {
+    @Operation(summary = "Calculates the dataverse tree metric",
+            description = "Calculates the released dataverse tree metric through the current month, optionally scoped to a released parent dataverse.")
+    public Response getDataversesTree(@Context UriInfo uriInfo,
+            @Parameter(description = "Alias of a released parent dataverse used to scope the metric.")
+            @QueryParam("parentAlias") String parentAlias) {
         return getDataversesTreeToMonth(uriInfo, MetricsUtil.getCurrentMonth(), parentAlias);
     }
 
     @GET
     @Path("tree/toMonth/{yyyymm}")
-    public Response getDataversesTreeToMonth(@Context UriInfo uriInfo, @PathParam("yyyymm") String yyyymm, @QueryParam("parentAlias") String parentAlias) {
+    @Operation(summary = "Calculates the dataverse tree metric through a month",
+            description = "Calculates the released dataverse tree metric through the specified month, optionally scoped to a released parent dataverse.")
+    public Response getDataversesTreeToMonth(@Context UriInfo uriInfo,
+            @Parameter(description = "Year and month cutoff for the metric, formatted as YYYYMM.", required = true)
+            @PathParam("yyyymm") String yyyymm,
+            @Parameter(description = "Alias of a released parent dataverse used to scope the metric.")
+            @QueryParam("parentAlias") String parentAlias) {
 
         Dataverse d = findDataverseOrDieIfNotFound(parentAlias);
 
diff --git a/src/main/java/edu/harvard/iq/dataverse/api/Notifications.java b/src/main/java/edu/harvard/iq/dataverse/api/Notifications.java
index ccb53d3a95a..42a28b4b6ff 100644
--- a/src/main/java/edu/harvard/iq/dataverse/api/Notifications.java
+++ b/src/main/java/edu/harvard/iq/dataverse/api/Notifications.java
@@ -19,18 +19,30 @@
 
 import static edu.harvard.iq.dataverse.util.json.JsonPrinter.json;
 import static edu.harvard.iq.dataverse.util.json.NullSafeJsonBuilder.jsonObjectBuilder;
+import org.eclipse.microprofile.openapi.annotations.Operation;
+import org.eclipse.microprofile.openapi.annotations.parameters.Parameter;
+import org.eclipse.microprofile.openapi.annotations.security.SecurityRequirement;
+import org.eclipse.microprofile.openapi.annotations.tags.Tag;
 
 @Stateless
 @Path("notifications")
+@SecurityRequirement(name = "DataverseApiKey")
+@Tag(name = "Notifications", description = "User notification lookup and notification preference operations.")
 public class Notifications extends AbstractApiBean {
 
     @GET
     @AuthRequired
     @Path("/all")
+    @Operation(summary = "Lists user notifications",
+            description = "Returns notifications for the authenticated user with optional unread filtering, formatting, and pagination.")
     public Response getAllNotificationsForUser(@Context ContainerRequestContext crc,
+                                               @Parameter(description = "Limit results to unread notifications.")
                                                @QueryParam("onlyUnread") boolean onlyUnread,
+                                               @Parameter(description = "Format notifications for in-app display.")
                                                @QueryParam("inAppNotificationFormat") boolean inAppNotificationFormat,
+                                               @Parameter(description = "Maximum number of notifications to return.")
                                                @QueryParam("limit") Integer limit,
+                                               @Parameter(description = "Number of notifications to skip before returning results.")
                                                @QueryParam("offset") Integer offset) {
         try {
             AuthenticatedUser authenticatedUser = getRequestAuthenticatedUserOrDie(crc);
@@ -45,6 +57,8 @@ public Response getAllNotificationsForUser(@Context ContainerRequestContext crc,
     @GET
     @AuthRequired
     @Path("/unreadCount")
+    @Operation(summary = "Returns unread notification count",
+            description = "Returns the number of unread notifications for the authenticated user.")
     public Response getUnreadNotificationsCountForUser(@Context ContainerRequestContext crc) {
         try {
             AuthenticatedUser au = getRequestAuthenticatedUserOrDie(crc);
@@ -59,7 +73,11 @@ public Response getUnreadNotificationsCountForUser(@Context ContainerRequestCont
     @PUT
     @AuthRequired
     @Path("/{id}/markAsRead")
-    public Response markNotificationAsReadForUser(@Context ContainerRequestContext crc, @PathParam("id") long id) {
+    @Operation(summary = "Marks a notification as read",
+            description = "Marks one notification as read when it belongs to the authenticated user.")
+    public Response markNotificationAsReadForUser(@Context ContainerRequestContext crc,
+            @Parameter(description = "Notification id to mark as read.", required = true)
+            @PathParam("id") long id) {
         try {
             AuthenticatedUser au = getRequestAuthenticatedUserOrDie(crc);
             Long userId = au.getId();
@@ -82,7 +100,11 @@ public Response markNotificationAsReadForUser(@Context ContainerRequestContext c
     @DELETE
     @AuthRequired
     @Path("/{id}")
-    public Response deleteNotificationForUser(@Context ContainerRequestContext crc, @PathParam("id") long id) {
+    @Operation(summary = "Deletes a notification",
+            description = "Deletes one notification when it belongs to the authenticated user.")
+    public Response deleteNotificationForUser(@Context ContainerRequestContext crc,
+            @Parameter(description = "Notification id to delete.", required = true)
+            @PathParam("id") long id) {
         try {
             AuthenticatedUser authenticatedUser = getRequestAuthenticatedUserOrDie(crc);
             Long userId = authenticatedUser.getId();
@@ -102,6 +124,8 @@ public Response deleteNotificationForUser(@Context ContainerRequestContext crc,
     @GET
     @AuthRequired
     @Path("/mutedEmails")
+    @Operation(summary = "Lists muted notification emails",
+            description = "Returns notification types whose emails are muted for the authenticated user.")
     public Response getMutedEmailsForUser(@Context ContainerRequestContext crc) {
         try {
             AuthenticatedUser authenticatedUser = getRequestAuthenticatedUserOrDie(crc);
@@ -119,7 +143,11 @@ public Response getMutedEmailsForUser(@Context ContainerRequestContext crc) {
     @PUT
     @AuthRequired
     @Path("/mutedEmails/{typeName}")
-    public Response muteEmailsForUser(@Context ContainerRequestContext crc, @PathParam("typeName") String typeName) {
+    @Operation(summary = "Mutes notification emails",
+            description = "Adds the specified notification type to the authenticated user's muted email preferences.")
+    public Response muteEmailsForUser(@Context ContainerRequestContext crc,
+            @Parameter(description = "Notification type name whose emails are muted.", required = true)
+            @PathParam("typeName") String typeName) {
         UserNotification.Type notificationType;
         try {
             notificationType = UserNotification.Type.valueOf(typeName);
@@ -141,7 +169,11 @@ public Response muteEmailsForUser(@Context ContainerRequestContext crc, @PathPar
     @DELETE
     @AuthRequired
     @Path("/mutedEmails/{typeName}")
-    public Response unmuteEmailsForUser(@Context ContainerRequestContext crc, @PathParam("typeName") String typeName) {
+    @Operation(summary = "Unmutes notification emails",
+            description = "Removes the specified notification type from the authenticated user's muted email preferences.")
+    public Response unmuteEmailsForUser(@Context ContainerRequestContext crc,
+            @Parameter(description = "Notification type name whose emails are unmuted.", required = true)
+            @PathParam("typeName") String typeName) {
         UserNotification.Type notificationType;
         try {
             notificationType = UserNotification.Type.valueOf(typeName);
@@ -163,6 +195,8 @@ public Response unmuteEmailsForUser(@Context ContainerRequestContext crc, @PathP
     @GET
     @AuthRequired
     @Path("/mutedNotifications")
+    @Operation(summary = "Lists muted in-app notifications",
+            description = "Returns notification types whose in-app notifications are muted for the authenticated user.")
     public Response getMutedNotificationsForUser(@Context ContainerRequestContext crc) {
         try {
             AuthenticatedUser authenticatedUser = getRequestAuthenticatedUserOrDie(crc);
@@ -180,7 +214,11 @@ public Response getMutedNotificationsForUser(@Context ContainerRequestContext cr
     @PUT
     @AuthRequired
     @Path("/mutedNotifications/{typeName}")
-    public Response muteNotificationsForUser(@Context ContainerRequestContext crc, @PathParam("typeName") String typeName) {
+    @Operation(summary = "Mutes in-app notifications",
+            description = "Adds the specified notification type to the authenticated user's muted in-app notification preferences.")
+    public Response muteNotificationsForUser(@Context ContainerRequestContext crc,
+            @Parameter(description = "Notification type name whose in-app notifications are muted.", required = true)
+            @PathParam("typeName") String typeName) {
         UserNotification.Type notificationType;
         try {
             notificationType = UserNotification.Type.valueOf(typeName);
@@ -202,7 +240,11 @@ public Response muteNotificationsForUser(@Context ContainerRequestContext crc, @
     @DELETE
     @AuthRequired
     @Path("/mutedNotifications/{typeName}")
-    public Response unmuteNotificationsForUser(@Context ContainerRequestContext crc, @PathParam("typeName") String typeName) {
+    @Operation(summary = "Unmutes in-app notifications",
+            description = "Removes the specified notification type from the authenticated user's muted in-app notification preferences.")
+    public Response unmuteNotificationsForUser(@Context ContainerRequestContext crc,
+            @Parameter(description = "Notification type name whose in-app notifications are unmuted.", required = true)
+            @PathParam("typeName") String typeName) {
         UserNotification.Type notificationType;
         try {
             notificationType = UserNotification.Type.valueOf(typeName);
diff --git a/src/main/java/edu/harvard/iq/dataverse/api/Pids.java b/src/main/java/edu/harvard/iq/dataverse/api/Pids.java
index 32d942f972c..9a5118474dc 100644
--- a/src/main/java/edu/harvard/iq/dataverse/api/Pids.java
+++ b/src/main/java/edu/harvard/iq/dataverse/api/Pids.java
@@ -30,6 +30,10 @@
 import jakarta.ws.rs.core.Context;
 import jakarta.ws.rs.core.MediaType;
 import jakarta.ws.rs.core.Response;
+import org.eclipse.microprofile.openapi.annotations.Operation;
+import org.eclipse.microprofile.openapi.annotations.parameters.Parameter;
+import org.eclipse.microprofile.openapi.annotations.security.SecurityRequirement;
+import org.eclipse.microprofile.openapi.annotations.tags.Tag;
 
 /**
  * PIDs are Persistent IDentifiers such as DOIs or Handles.
@@ -40,13 +44,19 @@
  */
 @Stateless
 @Path("pids")
+@SecurityRequirement(name = "DataverseApiKey")
+@Tag(name = "Admin", description = "Administrative Dataverse operations.")
 public class Pids extends AbstractApiBean {
 
     private static final Logger logger = Logger.getLogger(Pids.class.getName());
     @GET
     @AuthRequired
     @Produces(MediaType.APPLICATION_JSON)
-    public Response getPid(@Context ContainerRequestContext crc, @QueryParam("persistentId") String persistentId) {
+    @Operation(summary = "Returns PID provider metadata",
+            description = "Queries configured DataCite metadata for the supplied persistent identifier when the requester is a superuser.")
+    public Response getPid(@Context ContainerRequestContext crc,
+            @Parameter(description = "Persistent identifier to query.")
+            @QueryParam("persistentId") String persistentId) {
         User user = getRequestUser(crc);
         if (!user.isSuperuser()) {
             return error(Response.Status.FORBIDDEN, BundleUtil.getStringFromBundle("admin.api.auth.mustBeSuperUser"));
@@ -73,7 +83,11 @@ public Response getPid(@Context ContainerRequestContext crc, @QueryParam("persis
     @AuthRequired
     @Produces(MediaType.APPLICATION_JSON)
     @Path("unreserved")
-    public Response getUnreserved(@Context ContainerRequestContext crc, @QueryParam("persistentId") String persistentId) {
+    @Operation(summary = "Lists unreserved dataset PIDs",
+            description = "Returns draft datasets whose persistent identifiers have not been reserved when the requester is a superuser.")
+    public Response getUnreserved(@Context ContainerRequestContext crc,
+            @Parameter(description = "Optional persistent identifier value accepted by the endpoint.")
+            @QueryParam("persistentId") String persistentId) {
         User user = getRequestUser(crc);
         if (!user.isSuperuser()) {
             return error(Response.Status.FORBIDDEN, BundleUtil.getStringFromBundle("admin.api.auth.mustBeSuperUser"));
@@ -103,7 +117,11 @@ public Response getUnreserved(@Context ContainerRequestContext crc, @QueryParam(
     @AuthRequired
     @Produces(MediaType.APPLICATION_JSON)
     @Path("{id}/reserve")
-    public Response reservePid(@Context ContainerRequestContext crc, @PathParam("id") String idSupplied) {
+    @Operation(summary = "Reserves a dataset PID",
+            description = "Reserves the persistent identifier for the specified dataset.")
+    public Response reservePid(@Context ContainerRequestContext crc,
+            @Parameter(description = "Dataset id or persistent identifier whose PID is reserved.", required = true)
+            @PathParam("id") String idSupplied) {
         try {
             Dataset dataset = findDatasetOrDie(idSupplied);
             execCommand(new ReservePidCommand(createDataverseRequest(getRequestUser(crc)), dataset));
@@ -117,7 +135,11 @@ public Response reservePid(@Context ContainerRequestContext crc, @PathParam("id"
     @AuthRequired
     @Produces(MediaType.APPLICATION_JSON)
     @Path("{id}/delete")
-    public Response deletePid(@Context ContainerRequestContext crc, @PathParam("id") String idSupplied) {
+    @Operation(summary = "Deletes a draft dataset PID",
+            description = "Deletes the persistent identifier for an unpublished dataset.")
+    public Response deletePid(@Context ContainerRequestContext crc,
+            @Parameter(description = "Dataset id or persistent identifier whose PID is deleted.", required = true)
+            @PathParam("id") String idSupplied) {
         try {
             Dataset dataset = findDatasetOrDie(idSupplied);
             //Restrict to never-published datasets (that should have draft/nonpublic pids). The underlying code will invalidate
@@ -137,6 +159,8 @@ public Response deletePid(@Context ContainerRequestContext crc, @PathParam("id")
     @AuthRequired
     @Path("providers")
     @Produces(MediaType.APPLICATION_JSON)
+    @Operation(summary = "Lists PID providers",
+            description = "Returns the configured persistent identifier providers.")
     public Response getPidProviders(@Context ContainerRequestContext crc) throws WrappedResponse {
         try {
             getRequestAuthenticatedUserOrDie(crc);
@@ -152,7 +176,11 @@ public Response getPidProviders(@Context ContainerRequestContext crc) throws Wra
     // The :.+ suffix allows PIDs with a / char to be entered w/o escaping
     @Path("providers/{persistentId:.+}")
     @Produces(MediaType.APPLICATION_JSON)
-    public Response getPidProviderId(@Context ContainerRequestContext crc, @PathParam("persistentId") String persistentId) throws WrappedResponse {
+    @Operation(summary = "Returns the provider for a PID",
+            description = "Parses a persistent identifier and returns the managed provider id or reports that the PID belongs to an unmanaged provider.")
+    public Response getPidProviderId(@Context ContainerRequestContext crc,
+            @Parameter(description = "Persistent identifier whose provider is requested.", required = true)
+            @PathParam("persistentId") String persistentId) throws WrappedResponse {
         try {
             getRequestAuthenticatedUserOrDie(crc);
         } catch (WrappedResponse ex) {
diff --git a/src/main/java/edu/harvard/iq/dataverse/api/Prov.java b/src/main/java/edu/harvard/iq/dataverse/api/Prov.java
index 7f81ca20988..cf39e3499d4 100644
--- a/src/main/java/edu/harvard/iq/dataverse/api/Prov.java
+++ b/src/main/java/edu/harvard/iq/dataverse/api/Prov.java
@@ -33,8 +33,15 @@
 import jakarta.ws.rs.core.Response;
 import static jakarta.ws.rs.core.Response.Status.BAD_REQUEST;
 import static jakarta.ws.rs.core.Response.Status.FORBIDDEN;
+import org.eclipse.microprofile.openapi.annotations.Operation;
+import org.eclipse.microprofile.openapi.annotations.parameters.Parameter;
+import org.eclipse.microprofile.openapi.annotations.parameters.RequestBody;
+import org.eclipse.microprofile.openapi.annotations.security.SecurityRequirement;
+import org.eclipse.microprofile.openapi.annotations.tags.Tag;
 
 @Path("files")
+@SecurityRequirement(name = "DataverseApiKey")
+@Tag(name = "Files", description = "Data file metadata, upload, replacement, and editing operations.")
 public class Prov extends AbstractApiBean {
 
     private static final Logger logger = Logger.getLogger(Prov.class.getCanonicalName());
@@ -46,7 +53,15 @@ public class Prov extends AbstractApiBean {
     @AuthRequired
     @Path("{id}/prov-json")
     @Consumes("application/json")
-    public Response addProvJson(@Context ContainerRequestContext crc, String body, @PathParam("id") String idSupplied, @QueryParam("entityName") String entityName) {
+    @Operation(summary = "Adds PROV JSON to a data file",
+            description = "Validates and stores PROV JSON for a data file after checking that the requested entity name exists in the provenance graph.")
+    public Response addProvJson(@Context ContainerRequestContext crc,
+            @RequestBody(description = "PROV JSON document to validate and store for the data file.")
+            String body,
+            @Parameter(description = "Data file id or persistent identifier whose provenance is updated.", required = true)
+            @PathParam("id") String idSupplied,
+            @Parameter(description = "Entity name in the PROV JSON graph that represents the data file.", required = true)
+            @QueryParam("entityName") String entityName) {
         if(!systemConfig.isProvCollectionEnabled()) {
             return error(FORBIDDEN, BundleUtil.getStringFromBundle("api.prov.error.provDisabled"));
         }
@@ -85,7 +100,13 @@ public Response addProvJson(@Context ContainerRequestContext crc, String body, @
     @DELETE
     @AuthRequired
     @Path("{id}/prov-json")
-    public Response deleteProvJson(@Context ContainerRequestContext crc, String body, @PathParam("id") String idSupplied) {
+    @Operation(summary = "Deletes PROV JSON from a data file",
+            description = "Deletes stored PROV JSON from an unreleased data file.")
+    public Response deleteProvJson(@Context ContainerRequestContext crc,
+            @RequestBody(description = "Unused request body accepted by the endpoint.")
+            String body,
+            @Parameter(description = "Data file id or persistent identifier whose PROV JSON is deleted.", required = true)
+            @PathParam("id") String idSupplied) {
         if(!systemConfig.isProvCollectionEnabled()) {
             return error(FORBIDDEN, BundleUtil.getStringFromBundle("api.prov.error.provDisabled"));
         }
@@ -106,7 +127,13 @@ public Response deleteProvJson(@Context ContainerRequestContext crc, String body
     @AuthRequired
     @Path("{id}/prov-freeform")
     @Consumes("application/json")
-    public Response addProvFreeForm(@Context ContainerRequestContext crc, String body, @PathParam("id") String idSupplied) {
+    @Operation(summary = "Adds free-form provenance to a data file",
+            description = "Stores free-form provenance text for a data file from the text field of the supplied JSON and updates the dataset draft version.")
+    public Response addProvFreeForm(@Context ContainerRequestContext crc,
+            @RequestBody(description = "JSON object containing a text field with free-form provenance.")
+            String body,
+            @Parameter(description = "Data file id or persistent identifier whose free-form provenance is updated.", required = true)
+            @PathParam("id") String idSupplied) {
         if(!systemConfig.isProvCollectionEnabled()) {
             return error(FORBIDDEN, BundleUtil.getStringFromBundle("api.prov.error.provDisabled"));
         }
@@ -144,7 +171,13 @@ public Response addProvFreeForm(@Context ContainerRequestContext crc, String bod
     @GET
     @AuthRequired
     @Path("{id}/prov-freeform")
-    public Response getProvFreeForm(@Context ContainerRequestContext crc, String body, @PathParam("id") String idSupplied) {
+    @Operation(summary = "Returns free-form provenance for a data file",
+            description = "Returns stored free-form provenance text for the specified data file.")
+    public Response getProvFreeForm(@Context ContainerRequestContext crc,
+            @RequestBody(description = "Unused request body accepted by the endpoint.")
+            String body,
+            @Parameter(description = "Data file id or persistent identifier whose free-form provenance is returned.", required = true)
+            @PathParam("id") String idSupplied) {
         if(!systemConfig.isProvCollectionEnabled()) {
             return error(FORBIDDEN, BundleUtil.getStringFromBundle("api.prov.error.provDisabled"));
         }
@@ -164,7 +197,13 @@ public Response getProvFreeForm(@Context ContainerRequestContext crc, String bod
     @GET
     @AuthRequired
     @Path("{id}/prov-json")
-    public Response getProvJson(@Context ContainerRequestContext crc, String body, @PathParam("id") String idSupplied) {
+    @Operation(summary = "Returns PROV JSON for a data file",
+            description = "Returns stored PROV JSON for the specified data file.")
+    public Response getProvJson(@Context ContainerRequestContext crc,
+            @RequestBody(description = "Unused request body accepted by the endpoint.")
+            String body,
+            @Parameter(description = "Data file id or persistent identifier whose PROV JSON is returned.", required = true)
+            @PathParam("id") String idSupplied) {
         if(!systemConfig.isProvCollectionEnabled()) {
             return error(FORBIDDEN, BundleUtil.getStringFromBundle("api.prov.error.provDisabled"));
         }
diff --git a/src/main/java/edu/harvard/iq/dataverse/api/Roles.java b/src/main/java/edu/harvard/iq/dataverse/api/Roles.java
index 804416f0f8c..f4bc69260e6 100644
--- a/src/main/java/edu/harvard/iq/dataverse/api/Roles.java
+++ b/src/main/java/edu/harvard/iq/dataverse/api/Roles.java
@@ -21,6 +21,11 @@
 import jakarta.ws.rs.container.ContainerRequestContext;
 import jakarta.ws.rs.core.Context;
 import jakarta.ws.rs.core.Response;
+import org.eclipse.microprofile.openapi.annotations.Operation;
+import org.eclipse.microprofile.openapi.annotations.parameters.Parameter;
+import org.eclipse.microprofile.openapi.annotations.parameters.RequestBody;
+import org.eclipse.microprofile.openapi.annotations.security.SecurityRequirement;
+import org.eclipse.microprofile.openapi.annotations.tags.Tag;
 
 /**
  * Util API for managing roles. Might not make it to the production version.
@@ -28,12 +33,18 @@
  */
 @Stateless
 @Path("roles")
+@Tag(name = "Roles", description = "Role definition and role selection operations.")
 public class Roles extends AbstractApiBean {
 	
 	@GET
     @AuthRequired
 	@Path("{id}")
-	public Response viewRole(@Context ContainerRequestContext crc, @PathParam("id") String id) {
+    @SecurityRequirement(name = "DataverseApiKey")
+    @Operation(summary = "Returns a role",
+            description = "Returns a role definition when the authenticated user can manage permissions on the role owner.")
+	public Response viewRole(@Context ContainerRequestContext crc,
+            @Parameter(description = "Role id or alias to return.", required = true)
+            @PathParam("id") String id) {
         return response( ()-> {
             final User user = getRequestUser(crc);
             final DataverseRole role = findRoleOrDie(id);
@@ -45,7 +56,12 @@ public Response viewRole(@Context ContainerRequestContext crc, @PathParam("id")
     @DELETE
     @AuthRequired
     @Path("{id}")
-    public Response deleteRole(@Context ContainerRequestContext crc, @PathParam("id") String id) {
+    @SecurityRequirement(name = "DataverseApiKey")
+    @Operation(summary = "Deletes a role",
+            description = "Deletes a non-builtin role definition from its owner dataverse.")
+    public Response deleteRole(@Context ContainerRequestContext crc,
+            @Parameter(description = "Role id or alias to delete.", required = true)
+            @PathParam("id") String id) {
         return response(req -> {
             DataverseRole role = findRoleOrDie(id);
             List<String> args = Arrays.asList(role.getName());
@@ -59,8 +75,13 @@ public Response deleteRole(@Context ContainerRequestContext crc, @PathParam("id"
 	
 	@POST
     @AuthRequired
+    @SecurityRequirement(name = "DataverseApiKey")
+    @Operation(summary = "Creates a role",
+            description = "Creates a role definition in the specified dataverse and returns the saved role.")
 	public Response createNewRole(@Context ContainerRequestContext crc,
+                                  @RequestBody(description = "Role definition containing alias, name, permissions, and role metadata.")
                                   RoleDTO roleDto,
+                                  @Parameter(description = "Dataverse identifier where the role is created.", required = true)
                                   @QueryParam("dvo") String dvoIdtf) {
         return response( req -> ok(json(execCommand(
                                   new CreateRoleCommand(roleDto.asRole(),
@@ -70,6 +91,9 @@ public Response createNewRole(@Context ContainerRequestContext crc,
     @GET
     @AuthRequired
     @Path("userSelectable")
+    @SecurityRequirement(name = "DataverseApiKey")
+    @Operation(summary = "Lists selectable roles",
+            description = "Returns dataverse roles that the authenticated requester can select for role assignment.")
     public Response getUserSelectableRoles(@Context ContainerRequestContext crc) {
         return response(req -> ok(jsonDataverseRoles(roleAssigneeSvc.getSelectableDataverseRolesFor(req))), getRequestUser(crc));
     }
diff --git a/src/main/java/edu/harvard/iq/dataverse/api/SavedSearches.java b/src/main/java/edu/harvard/iq/dataverse/api/SavedSearches.java
index e6519c9ff36..cb4de9090dc 100644
--- a/src/main/java/edu/harvard/iq/dataverse/api/SavedSearches.java
+++ b/src/main/java/edu/harvard/iq/dataverse/api/SavedSearches.java
@@ -28,13 +28,20 @@
 import static jakarta.ws.rs.core.Response.Status.BAD_REQUEST;
 import static jakarta.ws.rs.core.Response.Status.INTERNAL_SERVER_ERROR;
 import static jakarta.ws.rs.core.Response.Status.NOT_FOUND;
+import org.eclipse.microprofile.openapi.annotations.Operation;
+import org.eclipse.microprofile.openapi.annotations.parameters.Parameter;
+import org.eclipse.microprofile.openapi.annotations.parameters.RequestBody;
+import org.eclipse.microprofile.openapi.annotations.tags.Tag;
 
 @Path("admin/savedsearches")
+@Tag(name = "Admin", description = "Administrative Dataverse operations.")
 public class SavedSearches extends AbstractApiBean {
 
     private static final Logger logger = Logger.getLogger(SavedSearches.class.getCanonicalName());
 
     @GET
+    @Operation(summary = "Lists saved-search endpoints",
+            description = "Returns a simple list of supported saved-search administration endpoint patterns.")
     public Response meta() {
         JsonArrayBuilder endpoints = Json.createArrayBuilder();
         endpoints.add("GET");
@@ -47,6 +54,8 @@ public Response meta() {
 
     @GET
     @Path("list")
+    @Operation(summary = "Lists saved searches",
+            description = "Returns all saved searches with query, filter queries, id, definition point, and creator id.")
     public Response list() {
         JsonArrayBuilder savedSearchesBuilder = Json.createArrayBuilder();
         List<SavedSearch> savedSearches = savedSearchSvc.findAll();
@@ -61,7 +70,11 @@ public Response list() {
 
     @GET
     @Path("{id}")
-    public Response show(@PathParam("id") long id) {
+    @Operation(summary = "Returns a saved search",
+            description = "Returns one saved search with query, filter queries, id, definition point, and creator id.")
+    public Response show(
+            @Parameter(description = "Numeric id of the saved search to return.", required = true)
+            @PathParam("id") long id) {
         SavedSearch savedSearch = savedSearchSvc.find(id);
         if (savedSearch != null) {
             JsonObjectBuilder response = toJson(savedSearch);
@@ -89,7 +102,11 @@ private JsonObjectBuilder toJson(SavedSearch savedSearch) {
     }
 
     @POST
-    public Response add(JsonObject body) {
+    @Operation(summary = "Creates a saved search",
+            description = "Creates a saved search from query, creator id, definition point id, and optional filter queries.")
+    public Response add(
+            @RequestBody(description = "Saved-search JSON containing creatorId, query, definitionPointId, and optional filterQueries.")
+            JsonObject body) {
         if (body == null) {
             return error(BAD_REQUEST, "JSON is expected.");
         }
@@ -172,7 +189,13 @@ public Response add(JsonObject body) {
 
     @DELETE
     @Path("{id}")
-    public Response delete(@PathParam("id") long doomedId, @QueryParam("unlink") boolean unlink) {
+    @Operation(summary = "Deletes a saved search",
+            description = "Deletes the specified saved search and optionally unlinks generated links.")
+    public Response delete(
+            @Parameter(description = "Numeric id of the saved search to delete.", required = true)
+            @PathParam("id") long doomedId,
+            @Parameter(description = "Remove links created from the saved search.")
+            @QueryParam("unlink") boolean unlink) {
         SavedSearch doomed = savedSearchSvc.find(doomedId);
         if (doomed == null) {
             return error(NOT_FOUND, "Could not find saved search id " + doomedId);
@@ -193,7 +216,11 @@ public Response delete(@PathParam("id") long doomedId, @QueryParam("unlink") boo
 
     @PUT
     @Path("makelinks/all")
-    public Response makeLinksForAllSavedSearches(@QueryParam("debug") boolean debug) {
+    @Operation(summary = "Creates links for all saved searches",
+            description = "Processes all saved searches and creates links for matching results.")
+    public Response makeLinksForAllSavedSearches(
+            @Parameter(description = "Include debug information in the link creation response.")
+            @QueryParam("debug") boolean debug) {
         JsonObjectBuilder makeLinksResponse;
         try {
             makeLinksResponse = savedSearchSvc.makeLinksForAllSavedSearches(debug);
@@ -207,7 +234,13 @@ public Response makeLinksForAllSavedSearches(@QueryParam("debug") boolean debug)
 
     @PUT
     @Path("makelinks/{id}")
-    public Response makeLinksForSingleSavedSearch(@PathParam("id") long savedSearchIdToLookUp, @QueryParam("debug") boolean debug) {
+    @Operation(summary = "Creates links for a saved search",
+            description = "Processes one saved search and creates links for matching results.")
+    public Response makeLinksForSingleSavedSearch(
+            @Parameter(description = "Numeric id of the saved search to process.", required = true)
+            @PathParam("id") long savedSearchIdToLookUp,
+            @Parameter(description = "Include debug information in the link creation response.")
+            @QueryParam("debug") boolean debug) {
         SavedSearch savedSearchToMakeLinksFor = savedSearchSvc.find(savedSearchIdToLookUp);
         if (savedSearchToMakeLinksFor == null) {
             return error(BAD_REQUEST, "Count not find saved search id " + savedSearchIdToLookUp);
diff --git a/src/main/java/edu/harvard/iq/dataverse/api/Search.java b/src/main/java/edu/harvard/iq/dataverse/api/Search.java
index 33beabd0f97..ee76411ac9c 100644
--- a/src/main/java/edu/harvard/iq/dataverse/api/Search.java
+++ b/src/main/java/edu/harvard/iq/dataverse/api/Search.java
@@ -37,12 +37,15 @@
 import jakarta.ws.rs.DefaultValue;
 import jakarta.ws.rs.core.Response;
 import org.apache.commons.lang3.StringUtils;
+import org.eclipse.microprofile.openapi.annotations.Operation;
+import org.eclipse.microprofile.openapi.annotations.tags.Tag;
 
 /**
  * User-facing documentation:
  * <a href="http://guides.dataverse.org/en/latest/api/search.html">http://guides.dataverse.org/en/latest/api/search.html</a>
  */
 @Path("search")
+@Tag(name = "Search", description = "Search and search service discovery operations.")
 public class Search extends AbstractApiBean {
 
     private static final Logger logger = Logger.getLogger(Search.class.getCanonicalName());
@@ -289,6 +292,8 @@ public Response search(
 
     @GET
     @Path("/services")
+    @Operation(summary = "Lists search services",
+            description = "Returns the configured search service names, display names, and the default search service.")
     public Response getSearchEngines() {
         Map<String, SearchService> availableEngines = searchServiceFactory.getAvailableServices();
         String defaultServiceName = JvmSettings.DEFAULT_SEARCH_SERVICE.lookupOptional().orElse(SearchServiceFactory.INTERNAL_SOLR_SERVICE_NAME);
diff --git a/src/main/java/edu/harvard/iq/dataverse/api/SendFeedbackAPI.java b/src/main/java/edu/harvard/iq/dataverse/api/SendFeedbackAPI.java
index 3bffcd042a3..b93e791318e 100644
--- a/src/main/java/edu/harvard/iq/dataverse/api/SendFeedbackAPI.java
+++ b/src/main/java/edu/harvard/iq/dataverse/api/SendFeedbackAPI.java
@@ -24,8 +24,13 @@
 
 import java.text.MessageFormat;
 import java.util.logging.Logger;
+import org.eclipse.microprofile.openapi.annotations.Operation;
+import org.eclipse.microprofile.openapi.annotations.parameters.RequestBody;
+import org.eclipse.microprofile.openapi.annotations.security.SecurityRequirement;
+import org.eclipse.microprofile.openapi.annotations.tags.Tag;
 
 @Path("sendfeedback")
+@Tag(name = "Users", description = "User account and authenticated user operations.")
 public class SendFeedbackAPI extends AbstractApiBean {
     private static final Logger logger = Logger.getLogger(SendFeedbackAPI.class.getCanonicalName());
     @EJB
@@ -36,10 +41,15 @@ public class SendFeedbackAPI extends AbstractApiBean {
      * This method mimics the contact form and sends an email to the contacts of the
      * specified Collection/Dataset/DataFile, optionally ccing the support email
      * address, or to the support email address when there is no target object.
-     **/
+    **/
     @POST
     @AuthRequired
-    public Response submitFeedback(@Context ContainerRequestContext crc, String jsonString) {
+    @SecurityRequirement(name = "DataverseApiKey")
+    @Operation(summary = "Submits feedback",
+            description = "Sends a feedback email to contacts for a target object or to the support address after validating the sender and message body.")
+    public Response submitFeedback(@Context ContainerRequestContext crc,
+            @RequestBody(description = "Feedback JSON with subject, body, optional sender email, and an optional target id or identifier.")
+            String jsonString) {
         try {
             JsonObject jsonObject = JsonUtil.getJsonObject(jsonString);
             if (!jsonObject.containsKey("subject") || !jsonObject.containsKey("body")) {
diff --git a/src/main/java/edu/harvard/iq/dataverse/api/SiteMap.java b/src/main/java/edu/harvard/iq/dataverse/api/SiteMap.java
index 37d6a2aa3fe..489260ec1b8 100644
--- a/src/main/java/edu/harvard/iq/dataverse/api/SiteMap.java
+++ b/src/main/java/edu/harvard/iq/dataverse/api/SiteMap.java
@@ -9,9 +9,12 @@
 import jakarta.ws.rs.Produces;
 import jakarta.ws.rs.core.MediaType;
 import jakarta.ws.rs.core.Response;
+import org.eclipse.microprofile.openapi.annotations.Operation;
+import org.eclipse.microprofile.openapi.annotations.tags.Tag;
 
 @Stateless
 @Path("admin/sitemap")
+@Tag(name = "Admin", description = "Administrative Dataverse operations.")
 public class SiteMap extends AbstractApiBean {
 
     @EJB
@@ -19,6 +22,8 @@ public class SiteMap extends AbstractApiBean {
 
     @POST
     @Produces(MediaType.APPLICATION_JSON)
+    @Operation(summary = "Starts a sitemap update",
+            description = "Starts regeneration of the site map for all dataverses and datasets when no staged sitemap file is present.")
     public Response updateSiteMap() {
         boolean stageFileExists = SiteMapUtil.stageFileExists();
         if (stageFileExists) {
diff --git a/src/main/java/edu/harvard/iq/dataverse/api/StorageSites.java b/src/main/java/edu/harvard/iq/dataverse/api/StorageSites.java
index 2915328428e..3ee77683d90 100644
--- a/src/main/java/edu/harvard/iq/dataverse/api/StorageSites.java
+++ b/src/main/java/edu/harvard/iq/dataverse/api/StorageSites.java
@@ -13,11 +13,18 @@
 import jakarta.ws.rs.Path;
 import jakarta.ws.rs.PathParam;
 import jakarta.ws.rs.core.Response;
+import org.eclipse.microprofile.openapi.annotations.Operation;
+import org.eclipse.microprofile.openapi.annotations.parameters.Parameter;
+import org.eclipse.microprofile.openapi.annotations.parameters.RequestBody;
+import org.eclipse.microprofile.openapi.annotations.tags.Tag;
 
 @Path("admin/storageSites")
+@Tag(name = "Admin", description = "Administrative Dataverse operations.")
 public class StorageSites extends AbstractApiBean {
 
     @GET
+    @Operation(summary = "Lists storage sites",
+            description = "Returns all configured storage sites as JSON.")
     public Response listAll() {
         List<StorageSite> storageSites = storageSiteSvc.findAll();
         if (storageSites != null && !storageSites.isEmpty()) {
@@ -33,7 +40,11 @@ public Response listAll() {
 
     @GET
     @Path("{id}")
-    public Response get(@PathParam("id") long id) {
+    @Operation(summary = "Returns a storage site",
+            description = "Returns the configured storage site with the specified numeric id.")
+    public Response get(
+            @Parameter(description = "Numeric id of the storage site to return.", required = true)
+            @PathParam("id") long id) {
         StorageSite storageSite = storageSiteSvc.find(id);
         if (storageSite == null) {
             return error(Response.Status.NOT_FOUND, "Could not find a storage site based on id " + id + ".");
@@ -42,7 +53,11 @@ public Response get(@PathParam("id") long id) {
     }
 
     @POST
-    public Response addSite(JsonObject jsonObject) {
+    @Operation(summary = "Creates a storage site",
+            description = "Parses and persists a storage site definition after validating that only one site is primary.")
+    public Response addSite(
+            @RequestBody(description = "Storage site definition to parse and persist.")
+            JsonObject jsonObject) {
         StorageSite toPersist = null;
         try {
             toPersist = StorageSiteUtil.parse(jsonObject);
@@ -65,7 +80,13 @@ public Response addSite(JsonObject jsonObject) {
 
     @PUT
     @Path("{id}/primaryStorage")
-    public Response setPrimary(@PathParam("id") long id, String input) {
+    @Operation(summary = "Sets primary storage for a site",
+            description = "Updates the primary-storage flag for the specified storage site after validating the primary-site constraint.")
+    public Response setPrimary(
+            @Parameter(description = "Numeric id of the storage site to update.", required = true)
+            @PathParam("id") long id,
+            @RequestBody(description = "Boolean text indicating whether the storage site is primary.")
+            String input) {
         StorageSite toModify = storageSiteSvc.find(id);
         if (toModify == null) {
             return error(Response.Status.NOT_FOUND, "Could not find a storage site based on id " + id + ".");
@@ -84,7 +105,11 @@ public Response setPrimary(@PathParam("id") long id, String input) {
 
     @DELETE
     @Path("{id}")
-    public Response delete(@PathParam("id") long id) {
+    @Operation(summary = "Deletes a storage site",
+            description = "Deletes the configured storage site with the specified numeric id.")
+    public Response delete(
+            @Parameter(description = "Numeric id of the storage site to delete.", required = true)
+            @PathParam("id") long id) {
         boolean deleted = storageSiteSvc.delete(id);
         if (deleted) {
             return ok("Storage site id  " + id + " has been deleted.");
diff --git a/src/main/java/edu/harvard/iq/dataverse/api/Users.java b/src/main/java/edu/harvard/iq/dataverse/api/Users.java
index af6b533d46d..b4151f37a16 100644
--- a/src/main/java/edu/harvard/iq/dataverse/api/Users.java
+++ b/src/main/java/edu/harvard/iq/dataverse/api/Users.java
@@ -37,6 +37,11 @@
 import jakarta.ws.rs.*;
 import jakarta.ws.rs.container.ContainerRequestContext;
 import jakarta.ws.rs.core.*;
+import org.eclipse.microprofile.openapi.annotations.Operation;
+import org.eclipse.microprofile.openapi.annotations.parameters.Parameter;
+import org.eclipse.microprofile.openapi.annotations.parameters.RequestBody;
+import org.eclipse.microprofile.openapi.annotations.security.SecurityRequirement;
+import org.eclipse.microprofile.openapi.annotations.tags.Tag;
 
 /**
  *
@@ -44,6 +49,7 @@
  */
 @Stateless
 @Path("users")
+@Tag(name = "Users", description = "User account and authenticated user operations.")
 public class Users extends AbstractApiBean {
     
     private static final Logger logger = Logger.getLogger(Users.class.getName());
@@ -51,7 +57,14 @@ public class Users extends AbstractApiBean {
     @POST
     @AuthRequired
     @Path("{consumedIdentifier}/mergeIntoUser/{baseIdentifier}")
-    public Response mergeInAuthenticatedUser(@Context ContainerRequestContext crc, @PathParam("consumedIdentifier") String consumedIdentifier, @PathParam("baseIdentifier") String baseIdentifier) {
+    @SecurityRequirement(name = "DataverseApiKey")
+    @Operation(summary = "Merges one user account into another",
+            description = "Moves account data from one authenticated user into another when the requester is a superuser.")
+    public Response mergeInAuthenticatedUser(@Context ContainerRequestContext crc,
+            @Parameter(description = "Identifier of the authenticated user account whose data is merged into another account.", required = true)
+            @PathParam("consumedIdentifier") String consumedIdentifier,
+            @Parameter(description = "Identifier of the authenticated user account that receives the merged account data.", required = true)
+            @PathParam("baseIdentifier") String baseIdentifier) {
         User u;
         try {
             u = getRequestUser(crc);
@@ -90,7 +103,14 @@ public Response mergeInAuthenticatedUser(@Context ContainerRequestContext crc, @
     @POST
     @AuthRequired
     @Path("{identifier}/changeIdentifier/{newIdentifier}")
-    public Response changeAuthenticatedUserIdentifier(@Context ContainerRequestContext crc, @PathParam("identifier") String oldIdentifier, @PathParam("newIdentifier")  String newIdentifier) {
+    @SecurityRequirement(name = "DataverseApiKey")
+    @Operation(summary = "Changes a user identifier",
+            description = "Changes an authenticated user's identifier when the requester is a superuser.")
+    public Response changeAuthenticatedUserIdentifier(@Context ContainerRequestContext crc,
+            @Parameter(description = "Current authenticated user identifier.", required = true)
+            @PathParam("identifier") String oldIdentifier,
+            @Parameter(description = "New authenticated user identifier to assign.", required = true)
+            @PathParam("newIdentifier") String newIdentifier) {
         User u;
         try {
             u = getRequestUser(crc);
@@ -124,6 +144,9 @@ public Response changeAuthenticatedUserIdentifier(@Context ContainerRequestConte
     @Path("token")
     @AuthRequired
     @DELETE
+    @SecurityRequirement(name = "DataverseApiKey")
+    @Operation(summary = "Deletes the current user's API token",
+            description = "Removes the API token for the authenticated user.")
     public Response deleteToken(@Context ContainerRequestContext crc) {
         User u = getRequestUser(crc);
         AuthenticatedUser au;
@@ -143,6 +166,9 @@ public Response deleteToken(@Context ContainerRequestContext crc) {
     @Path("token")
     @AuthRequired
     @GET
+    @SecurityRequirement(name = "DataverseApiKey")
+    @Operation(summary = "Returns the current user's API token expiration",
+            description = "Returns the authenticated user's API token string and expiration time.")
     public Response getTokenExpirationDate(@Context ContainerRequestContext crc) {
         try {
             AuthenticatedUser user = getRequestAuthenticatedUserOrDie(crc);
@@ -162,7 +188,12 @@ public Response getTokenExpirationDate(@Context ContainerRequestContext crc) {
     @Path("token/recreate")
     @AuthRequired
     @POST
-    public Response recreateToken(@Context ContainerRequestContext crc, @QueryParam("returnExpiration") boolean returnExpiration) {
+    @SecurityRequirement(name = "DataverseApiKey")
+    @Operation(summary = "Recreates the current user's API token",
+            description = "Deletes the authenticated user's existing API token, creates a new token, and optionally includes its expiration time in the response.")
+    public Response recreateToken(@Context ContainerRequestContext crc,
+            @Parameter(description = "Include the new token expiration time in the response.")
+            @QueryParam("returnExpiration") boolean returnExpiration) {
         User u = getRequestUser(crc);
 
         AuthenticatedUser au;        
@@ -190,6 +221,9 @@ public Response recreateToken(@Context ContainerRequestContext crc, @QueryParam(
     @GET
     @AuthRequired
     @Path(":me")
+    @SecurityRequirement(name = "DataverseApiKey")
+    @Operation(summary = "Returns the authenticated user",
+            description = "Returns the authenticated user associated with the supplied API token or active API session.")
     public Response getAuthenticatedUserByToken(@Context ContainerRequestContext crc) {
 
         String tokenFromRequestAPI = getRequestApiKey();
@@ -211,7 +245,12 @@ public Response getAuthenticatedUserByToken(@Context ContainerRequestContext crc
     @POST
     @AuthRequired
     @Path("{identifier}/removeRoles")
-    public Response removeUserRoles(@Context ContainerRequestContext crc, @PathParam("identifier") String identifier) {
+    @SecurityRequirement(name = "DataverseApiKey")
+    @Operation(summary = "Removes all roles from a user",
+            description = "Revokes all role assignments for the specified authenticated user.")
+    public Response removeUserRoles(@Context ContainerRequestContext crc,
+            @Parameter(description = "Authenticated user identifier whose role assignments are removed.", required = true)
+            @PathParam("identifier") String identifier) {
         try {
             AuthenticatedUser userToModify = authSvc.getAuthenticatedUser(identifier);
             if (userToModify == null) {
@@ -227,7 +266,12 @@ public Response removeUserRoles(@Context ContainerRequestContext crc, @PathParam
     @GET
     @AuthRequired
     @Path("{identifier}/traces")
-    public Response getTraces(@Context ContainerRequestContext crc, @PathParam("identifier") String identifier) {
+    @SecurityRequirement(name = "DataverseApiKey")
+    @Operation(summary = "Returns user traces",
+            description = "Returns trace information showing where the specified authenticated user appears across role assignments, groups, datasets, files, guestbooks, and saved searches.")
+    public Response getTraces(@Context ContainerRequestContext crc,
+            @Parameter(description = "Authenticated user identifier whose traces are returned.", required = true)
+            @PathParam("identifier") String identifier) {
         try {
             AuthenticatedUser userToQuery = authSvc.getAuthenticatedUser(identifier);
             JsonObjectBuilder jsonObj = execCommand(new GetUserTracesCommand(createDataverseRequest(getRequestUser(crc)), userToQuery, null));
@@ -243,7 +287,14 @@ public Response getTraces(@Context ContainerRequestContext crc, @PathParam("iden
     @AuthRequired
     @Path("{identifier}/traces/{element}")
     @Produces("text/csv, application/json")
-    public Response getTracesElement(@Context ContainerRequestContext crc, @Context Request req, @PathParam("identifier") String identifier, @PathParam("element") String element) {
+    @SecurityRequirement(name = "DataverseApiKey")
+    @Operation(summary = "Returns a user trace element",
+            description = "Returns one category of trace information for the specified authenticated user as JSON or CSV.")
+    public Response getTracesElement(@Context ContainerRequestContext crc, @Context Request req,
+            @Parameter(description = "Authenticated user identifier whose trace element is returned.", required = true)
+            @PathParam("identifier") String identifier,
+            @Parameter(description = "Trace category to return, such as roleAssignments, explicitGroups, guestbookEntries, or savedSearches.", required = true)
+            @PathParam("element") String element) {
         try {
             AuthenticatedUser userToQuery = authSvc.getAuthenticatedUser(identifier);
             if(!elements.contains(element)) {
@@ -276,7 +327,14 @@ public Response getTracesElement(@Context ContainerRequestContext crc, @Context
     @AuthRequired
     @Path("{identifier}/allowedCollections/{permission}")
     @Produces("application/json")
-    public Response getUserPermittedCollections(@Context ContainerRequestContext crc, @Context Request req, @PathParam("identifier") String identifier, @PathParam("permission") String permission) {
+    @SecurityRequirement(name = "DataverseApiKey")
+    @Operation(summary = "Lists collections permitted for a user",
+            description = "Returns collections where the specified user has the requested permission when the requester is that user or a superuser.")
+    public Response getUserPermittedCollections(@Context ContainerRequestContext crc, @Context Request req,
+            @Parameter(description = "Authenticated user identifier whose permitted collections are returned.", required = true)
+            @PathParam("identifier") String identifier,
+            @Parameter(description = "Permission name used to select permitted collections.", required = true)
+            @PathParam("permission") String permission) {
         AuthenticatedUser authenticatedUser = null;
         try {
             authenticatedUser = getRequestAuthenticatedUserOrDie(crc);
@@ -297,7 +355,11 @@ public Response getUserPermittedCollections(@Context ContainerRequestContext crc
 
     @POST
     @Path("register")
-    public Response registerOIDCUser(String body) {
+    @Operation(summary = "Registers an OIDC user",
+            description = "Registers an OIDC user from the supplied user JSON when API bearer authentication is enabled and a bearer token is present.")
+    public Response registerOIDCUser(
+            @RequestBody(description = "User JSON parsed into a new authenticated OIDC user registration.")
+            String body) {
         if (!FeatureFlags.API_BEARER_AUTH.enabled()) {
             return error(Response.Status.INTERNAL_SERVER_ERROR, BundleUtil.getStringFromBundle("users.api.errors.bearerAuthFeatureFlagDisabled"));
         }
diff --git a/src/main/java/edu/harvard/iq/dataverse/api/Workflows.java b/src/main/java/edu/harvard/iq/dataverse/api/Workflows.java
index 7bd19b3a403..c5891f7d36a 100644
--- a/src/main/java/edu/harvard/iq/dataverse/api/Workflows.java
+++ b/src/main/java/edu/harvard/iq/dataverse/api/Workflows.java
@@ -15,6 +15,10 @@
 import jakarta.ws.rs.Path;
 import jakarta.ws.rs.PathParam;
 import jakarta.ws.rs.core.Response;
+import org.eclipse.microprofile.openapi.annotations.Operation;
+import org.eclipse.microprofile.openapi.annotations.parameters.Parameter;
+import org.eclipse.microprofile.openapi.annotations.parameters.RequestBody;
+import org.eclipse.microprofile.openapi.annotations.tags.Tag;
 
 /**
  * API Endpoint for external systems to report the results of workflow step
@@ -24,6 +28,7 @@
  * @author michael
  */
 @Path("workflows")
+@Tag(name = "Workflows", description = "Workflow callback operations.")
 public class Workflows extends AbstractApiBean {
     
     @EJB
@@ -34,7 +39,13 @@ public class Workflows extends AbstractApiBean {
     
     @Path("{invocationId}")
     @POST
-    public Response resumeWorkflow( @PathParam("invocationId") String invocationId, String body ) {
+    @Operation(summary = "Resumes a pending workflow",
+            description = "Accepts the result body from an external workflow step and resumes the pending workflow invocation when the caller IP address is allowed.")
+    public Response resumeWorkflow(
+            @Parameter(description = "Identifier of the pending workflow invocation to resume.", required = true)
+            @PathParam("invocationId") String invocationId,
+            @RequestBody(description = "Workflow step result body passed to the pending invocation.")
+            String body) {
         PendingWorkflowInvocation pending = workflows.getPendingWorkflow(invocationId);
         
         String remoteAddrStr = httpRequest.getRemoteAddr();
diff --git a/src/main/java/edu/harvard/iq/dataverse/api/WorkflowsAdmin.java b/src/main/java/edu/harvard/iq/dataverse/api/WorkflowsAdmin.java
index ecb7248cae9..21b82505616 100644
--- a/src/main/java/edu/harvard/iq/dataverse/api/WorkflowsAdmin.java
+++ b/src/main/java/edu/harvard/iq/dataverse/api/WorkflowsAdmin.java
@@ -25,12 +25,17 @@
 import jakarta.ws.rs.Path;
 import jakarta.ws.rs.PathParam;
 import jakarta.ws.rs.core.Response;
+import org.eclipse.microprofile.openapi.annotations.Operation;
+import org.eclipse.microprofile.openapi.annotations.parameters.Parameter;
+import org.eclipse.microprofile.openapi.annotations.parameters.RequestBody;
+import org.eclipse.microprofile.openapi.annotations.tags.Tag;
 
 /**
  * API Endpoint for managing workflows.
  * @author michael
  */
 @Path("admin/workflows")
+@Tag(name = "Workflows", description = "Workflow administration operations.")
 public class WorkflowsAdmin extends AbstractApiBean {
     
     public static final String IP_SEPARATOR = ";";
@@ -40,7 +45,11 @@ public class WorkflowsAdmin extends AbstractApiBean {
     WorkflowServiceBean workflows;
     
     @POST
-    public Response addWorkflow(JsonObject jsonWorkflow) {
+    @Operation(summary = "Creates a workflow",
+            description = "Parses a workflow definition, saves it, and returns the created workflow.")
+    public Response addWorkflow(
+            @RequestBody(description = "Workflow definition to parse and persist.")
+            JsonObject jsonWorkflow) {
         JsonParser jp = new JsonParser();
         try {
             Workflow wf = jp.parseWorkflow(jsonWorkflow);
@@ -53,6 +62,8 @@ public Response addWorkflow(JsonObject jsonWorkflow) {
     }
     
     @GET
+    @Operation(summary = "Lists workflows",
+            description = "Returns brief JSON entries for all configured workflows.")
     public Response listWorkflows() {
         return ok( workflows.listWorkflows().stream()
                             .map(wf->brief.json(wf)).collect(toJsonArray()) );
@@ -60,7 +71,13 @@ public Response listWorkflows() {
     
     @Path("default/{triggerType}")
     @PUT
-    public Response setDefault(@PathParam("triggerType") String triggerType, String identifier) {
+    @Operation(summary = "Sets a default workflow",
+            description = "Sets the workflow id used by default for the specified workflow trigger type.")
+    public Response setDefault(
+            @Parameter(description = "Workflow trigger type that receives the default workflow.", required = true)
+            @PathParam("triggerType") String triggerType,
+            @RequestBody(description = "Numeric workflow id to use as the default for the trigger type.")
+            String identifier) {
         try {
             long idtf = Long.parseLong(identifier.trim());
             TriggerType tt = TriggerType.valueOf(triggerType);
@@ -80,6 +97,8 @@ public Response setDefault(@PathParam("triggerType") String triggerType, String
     
     @Path("default/")
     @GET
+    @Operation(summary = "Lists default workflows",
+            description = "Returns each workflow trigger type with its configured default workflow or null when no default is set.")
     public Response listDefaults() {
         JsonObjectBuilder bld = Json.createObjectBuilder();
         for ( TriggerType tp : TriggerType.values() ) {
@@ -93,7 +112,11 @@ public Response listDefaults() {
     
     @Path("default/{triggerType}")
     @GET
-    public Response getDefault(@PathParam("triggerType") String triggerType) {
+    @Operation(summary = "Returns a default workflow",
+            description = "Returns the default workflow configured for the specified trigger type.")
+    public Response getDefault(
+            @Parameter(description = "Workflow trigger type whose default workflow is requested.", required = true)
+            @PathParam("triggerType") String triggerType) {
         try {
             return workflows.getDefaultWorkflow(TriggerType.valueOf(triggerType))
                             .map( wf -> ok(json(wf)) )
@@ -105,7 +128,11 @@ public Response getDefault(@PathParam("triggerType") String triggerType) {
     
     @Path("default/{triggerType}")
     @DELETE
-    public Response deleteDefault(@PathParam("triggerType") String triggerType) {
+    @Operation(summary = "Clears a default workflow",
+            description = "Removes the default workflow assignment for the specified trigger type.")
+    public Response deleteDefault(
+            @Parameter(description = "Workflow trigger type whose default assignment is removed.", required = true)
+            @PathParam("triggerType") String triggerType) {
         try {
             workflows.setDefaultWorkflowId(TriggerType.valueOf(triggerType), null);
             return ok("default workflow for trigger " + triggerType + " unset.");
@@ -116,7 +143,11 @@ public Response deleteDefault(@PathParam("triggerType") String triggerType) {
     
     @Path("/{id}")
     @GET
-    public Response getWorkflow(@PathParam("id") String identifier ) {
+    @Operation(summary = "Returns a workflow",
+            description = "Returns the workflow with the specified numeric id.")
+    public Response getWorkflow(
+            @Parameter(description = "Numeric id of the workflow to return.", required = true)
+            @PathParam("id") String identifier ) {
         try {
             long idtf = Long.parseLong(identifier);
             return workflows.getWorkflow(idtf)
@@ -129,7 +160,11 @@ public Response getWorkflow(@PathParam("id") String identifier ) {
     
     @Path("/{id}")
     @DELETE
-    public Response deleteWorkflow(@PathParam("id") String id ) {
+    @Operation(summary = "Deletes a workflow",
+            description = "Deletes the workflow with the specified numeric id unless it is configured as a default workflow.")
+    public Response deleteWorkflow(
+            @Parameter(description = "Numeric id of the workflow to delete.", required = true)
+            @PathParam("id") String id ) {
         try {
             long idtf = Long.parseLong(id);
             return workflows.deleteWorkflow(idtf) ? ok("Workflow " + idtf + " deleted") 
@@ -155,13 +190,19 @@ public Response deleteWorkflow(@PathParam("id") String id ) {
     
     @Path("/ip-whitelist")
     @GET
+    @Operation(summary = "Returns the workflow IP allowlist",
+            description = "Returns the semicolon-separated IP addresses allowed to resume external workflow steps.")
     public Response getIpWhitelist() {
         return ok( settingsSvc.getValueForKey(WorkflowsAdminIpWhitelist, DEFAULT_IP_ALLOWLIST) );
     }
     
     @Path("/ip-whitelist")
     @PUT
-    public Response setIpWhitelist(String body) {
+    @Operation(summary = "Sets the workflow IP allowlist",
+            description = "Validates and stores the semicolon-separated IP addresses allowed to resume external workflow steps.")
+    public Response setIpWhitelist(
+            @RequestBody(description = "Semicolon-separated IP addresses allowed to resume external workflow steps.")
+            String body) {
         String ipList = body.trim();
         String[] ips = ipList.split(IP_SEPARATOR);
         boolean allIpsOk = Arrays.stream(ips).allMatch(ip->{
@@ -182,6 +223,8 @@ public Response setIpWhitelist(String body) {
     
     @Path("/ip-whitelist")
     @DELETE
+    @Operation(summary = "Resets the workflow IP allowlist",
+            description = "Deletes the configured workflow IP allowlist so the default localhost allowlist is used.")
     public Response deleteIpWhitelist() {
         settingsSvc.deleteValueForKey(WorkflowsAdminIpWhitelist);
         return ok( "Restored whitelist to default (127.0.0.1;::1)" );
diff --git a/src/main/java/edu/harvard/iq/dataverse/api/batchjob/BatchJobResource.java b/src/main/java/edu/harvard/iq/dataverse/api/batchjob/BatchJobResource.java
index 09a60b1b700..faf0e5041fc 100644
--- a/src/main/java/edu/harvard/iq/dataverse/api/batchjob/BatchJobResource.java
+++ b/src/main/java/edu/harvard/iq/dataverse/api/batchjob/BatchJobResource.java
@@ -18,10 +18,14 @@
 import java.util.ArrayList;
 import java.util.List;
 import java.util.Set;
+import org.eclipse.microprofile.openapi.annotations.Operation;
+import org.eclipse.microprofile.openapi.annotations.parameters.Parameter;
+import org.eclipse.microprofile.openapi.annotations.tags.Tag;
 
 
 @Stateless
 @Path("admin/batch")
+@Tag(name = "Admin", description = "Administrative Dataverse operations.")
 public class BatchJobResource extends AbstractApiBean {
 
     private static String EMPTY_JSON_LIST = "[]";
@@ -31,6 +35,8 @@ public class BatchJobResource extends AbstractApiBean {
     @GET
     @Path("/jobs")
     @Produces(MediaType.APPLICATION_JSON)
+    @Operation(summary = "Lists batch jobs",
+            description = "Returns JSON containing the execution records for all known batch job instances.")
     public Response listBatchJobs() {
         try {
             final List<JobExecutionEntity> executionEntities = new ArrayList<>();
@@ -55,7 +61,11 @@ public Response listBatchJobs() {
     @GET
     @Path("/jobs/name/{jobName}")
     @Produces(MediaType.APPLICATION_JSON)
-    public Response listBatchJobsByName( @PathParam("jobName") String jobName) {
+    @Operation(summary = "Lists batch jobs by name",
+            description = "Returns JSON containing execution records for batch job instances with the specified job name.")
+    public Response listBatchJobsByName(
+            @Parameter(description = "Batch job name used to select job instances.", required = true)
+            @PathParam("jobName") String jobName) {
         try {
             final List<JobExecutionEntity> executionEntities = new ArrayList<>();
             final JobOperator jobOperator = BatchRuntime.getJobOperator();
@@ -77,7 +87,11 @@ public Response listBatchJobsByName( @PathParam("jobName") String jobName) {
     @GET
     @Path("/jobs/{jobId}")
     @Produces(MediaType.APPLICATION_JSON)
-    public Response listBatchJobById(@PathParam("jobId") String jobId) {
+    @Operation(summary = "Returns a batch job execution",
+            description = "Returns the execution record for the specified batch job execution id as JSON.")
+    public Response listBatchJobById(
+            @Parameter(description = "Numeric batch job execution id.", required = true)
+            @PathParam("jobId") String jobId) {
         try {
             JobExecution execution = BatchRuntime.getJobOperator().getJobExecution(Long.valueOf(jobId));
             return Response.ok(mapper.writeValueAsString(JobExecutionEntity.create(execution))).build();
@@ -86,4 +100,4 @@ public Response listBatchJobById(@PathParam("jobId") String jobId) {
         }
     }
 
-}
\ No newline at end of file
+}
diff --git a/src/main/java/edu/harvard/iq/dataverse/api/batchjob/FileRecordJobResource.java b/src/main/java/edu/harvard/iq/dataverse/api/batchjob/FileRecordJobResource.java
index b7a6b7cfafd..54da8831bff 100644
--- a/src/main/java/edu/harvard/iq/dataverse/api/batchjob/FileRecordJobResource.java
+++ b/src/main/java/edu/harvard/iq/dataverse/api/batchjob/FileRecordJobResource.java
@@ -21,10 +21,15 @@
 import java.util.logging.Logger;
 import jakarta.json.Json;
 import jakarta.json.JsonObject;
+import org.eclipse.microprofile.openapi.annotations.Operation;
+import org.eclipse.microprofile.openapi.annotations.parameters.Parameter;
+import org.eclipse.microprofile.openapi.annotations.security.SecurityRequirement;
+import org.eclipse.microprofile.openapi.annotations.tags.Tag;
 
 @Stateless
 @Path("batch/jobs")
 @Produces(MediaType.APPLICATION_JSON)
+@Tag(name = "Admin", description = "Administrative Dataverse operations.")
 public class FileRecordJobResource extends AbstractApiBean {
 
     private static final Logger logger = Logger.getLogger(FileRecordJobResource.class.getName());
@@ -39,11 +44,18 @@ public class FileRecordJobResource extends AbstractApiBean {
     @AuthRequired
     @Path("import/datasets/files/{identifier}")
     @Produces(MediaType.APPLICATION_JSON)
+    @SecurityRequirement(name = "DataverseApiKey")
+    @Operation(summary = "Starts a file-system import job",
+            description = "Starts a background job that imports files from a server-side upload folder into the specified dataset and returns the job execution id.")
     public Response getFilesystemImport(@Context ContainerRequestContext crc,
+                                        @Parameter(description = "Dataset id or persistent identifier that receives the imported files.", required = true)
                                         @PathParam("identifier") String identifier,
+                                        @Parameter(description = "Import mode requested for the file-system import job.")
                                         @QueryParam("mode") @DefaultValue("MERGE") String mode,
                                         /*@QueryParam("fileMode") @DefaultValue("package_file") String fileMode*/
+                                        @Parameter(description = "Server-side upload folder containing files to import.")
                                         @QueryParam("uploadFolder") String uploadFolder,
+                                        @Parameter(description = "Total size in bytes expected for the imported files.")
                                         @QueryParam("totalSize") Long totalSize) {
         return response(req -> {
             ImportMode importMode = ImportMode.MERGE;