OpenAPI definition endpoint

doc/release-notes/10236-openapi-definition-endpoint.md

@@ -0,0 +1,8 @@
+On Dataverse 6.0 Payara was updated and this caused the url `/openapi/` to stop working and caused an exception on the server.
+
+- https://github.com/IQSS/dataverse/issues/9981
+- https://github.com/payara/Payara/issues/6369
+
+We incorporated the SmallRye OpenAPI plugin on our POM (https://github.com/smallrye/smallrye-open-api/tree/main/tools/maven-plugin) which will generate files for YAML and JSON formats and deposit them on `edu/harvard/iq/dataverse/openapi/ `these files will be provided by this endpoint depending on the format requested.
+
+The API endpoint was added `/api/info/openapi/{format}` accepting the "json" and "yaml" as formats.

pom.xml

@@ -32,6 +32,10 @@
         <poi.version>5.2.1</poi.version>
         <tika.version>2.4.1</tika.version>
         <netcdf.version>5.5.3</netcdf.version>
+
+        <smallrye.schemaFilename>dataverse_openapi</smallrye.schemaFilename>
+        <smallrye.infoTitle>Dataverse API</smallrye.infoTitle>
+        <smallrye.outputDirectory>src/main/resources/edu/harvard/iq/dataverse/openapi</smallrye.outputDirectory>
     </properties>
 
     <!-- Versions of dependencies used both directly and transitive are managed here.
@@ -682,6 +686,7 @@
                     <include>**/firstNames/*.*</include>
                     <include>**/*.xsl</include>
                     <include>**/services/*</include>
+                    <include>**/openapi/*</include>
                 </includes>
             </resource>
             <resource>
@@ -694,6 +699,22 @@
             </resource>
         </resources>
         <plugins>
+            <plugin>
+                <artifactId>smallrye-open-api-maven-plugin</artifactId>
+                <groupId>io.smallrye</groupId>
+                <executions>
+                    <execution>
+                        <goals>
+                            <goal>generate-schema</goal>
+                        </goals>
+                    </execution>
+                </executions>
+                <configuration>
+                    <schemaFilename>${smallrye.schemaFilename}</schemaFilename>
+                    <infoTitle>${smallrye.infoTitle}</infoTitle>
+                    <outputDirectory>${smallrye.outputDirectory}</outputDirectory>
+                </configuration>
+            </plugin>
             <plugin>
                 <groupId>org.apache.maven.plugins</groupId>
                 <artifactId>maven-compiler-plugin</artifactId>

src/main/java/edu/harvard/iq/dataverse/api/Info.java

@@ -1,13 +1,26 @@
 package edu.harvard.iq.dataverse.api;
 
+import java.io.InputStream;
+import java.nio.charset.StandardCharsets;
+import java.util.Arrays;
+import java.util.List;
+import java.util.logging.Level;
+import java.util.logging.Logger;
+
+import org.apache.commons.io.IOUtils;
+
 import edu.harvard.iq.dataverse.settings.JvmSettings;
 import edu.harvard.iq.dataverse.settings.SettingsServiceBean;
+import edu.harvard.iq.dataverse.util.BundleUtil;
+import edu.harvard.iq.dataverse.util.FileUtil;
 import edu.harvard.iq.dataverse.util.SystemConfig;
 import jakarta.ejb.EJB;
 import jakarta.json.Json;
 import jakarta.json.JsonValue;
 import jakarta.ws.rs.GET;
 import jakarta.ws.rs.Path;
+import jakarta.ws.rs.PathParam;
+import jakarta.ws.rs.core.MediaType;
 import jakarta.ws.rs.core.Response;
 
 @Path("info")
@@ -19,6 +32,8 @@ public class Info extends AbstractApiBean {
     @EJB
     SystemConfig systemConfig;
 
+    private static final Logger logger = Logger.getLogger(Info.class.getCanonicalName());
+
     @GET
     @Path("settings/:DatasetPublishPopupCustomText")
     public Response getDatasetPublishPopupCustomText() {
@@ -55,6 +70,52 @@ public Response getTermsOfUse() {
         return ok(systemConfig.getApiTermsOfUse());
     }
 
+    /*
+     * On Dataverse 6.0 Payara was updated and the openapi endpoint stopped working: https://github.com/payara/Payara/issues/6369
+     * 
+     * This caused the url /openapi/ to stop working and caused an exception on the server: https://github.com/IQSS/dataverse/issues/9981
+     * 
+     * We incorporated the SmallRye OpenAPI plugin on our POM (https://github.com/smallrye/smallrye-open-api/tree/main/tools/maven-plugin) 
+     * which will generate files for YAML and JSON formats and deposit them on edu/harvard/iq/dataverse/openapi/
+     * these files will be provided by this endpoint depending on the format requested.
+     * 
+     */
+    @GET
+    @Path("openapi/{format}")
+    public Response getOpenapiSpec(@PathParam("format") String format) {
+
+        //We use the lowercase of the specified format to define the mediatype and will be used as the file extension.
+        String requestedFormat = format.toLowerCase();
+        MediaType mediaType = null;
+
+        if (requestedFormat.equals("json")){
+            mediaType = MediaType.APPLICATION_JSON_TYPE;
+        } else if (requestedFormat.equals("yaml")){
+            mediaType = MediaType.TEXT_PLAIN_TYPE;
+        } else {
+            //If the format is not supported we will return a 400 Bad Request
+            List<String> args = Arrays.asList(format);
+            String bundleResponse = BundleUtil.getStringFromBundle("info.api.exception.invalid.format", args);
+            return error(Response.Status.BAD_REQUEST, bundleResponse);
+        }
+
+        try {
+            //We create an input stream based on the requested format and will return the content of the file as a response.
+            String baseFileName = "edu/harvard/iq/dataverse/openapi/dataverse_openapi." + requestedFormat;
+            InputStream openapiDefinitionStream  = Info.class.getClassLoader().getResourceAsStream(baseFileName); 
+            return Response.ok().entity(IOUtils.toString(openapiDefinitionStream, StandardCharsets.UTF_8))
+                        .type(mediaType).build();
+        } catch (Exception ex) {
+            //If a supported file is not found we will return a 400 Bad Request with an exception.
+            logger.log(Level.SEVERE, "OpenApi Definition format not found " + format + ":" + ex.getMessage(), ex);
+            List<String> args = Arrays.asList(format);
+            String bundleResponse = BundleUtil.getStringFromBundle("info.api.exception", args);
+            return error(Response.Status.BAD_REQUEST, bundleResponse);  
+        }        
+    }
+
+
+
     @GET
     @Path("settings/incompleteMetadataViaApi")
     public Response getAllowsIncompleteMetadata() {

src/main/java/propertyFiles/Bundle.properties

@@ -2948,3 +2948,7 @@ publishDatasetCommand.pidNotReserved=Cannot publish dataset because its persiste
 api.errors.invalidApiToken=Invalid API token.
 api.ldninbox.citation.alert={0},<br><br> The {1} has just been notified that the {2}, <a href=''{3}''>{3}</a>, cites "<a href=''{4}/dataset.xhtml?persistentId={5}''>{6}</a>" in this repository.
 api.ldninbox.citation.subject={0}: A Dataset Citation has been reported!
+
+#Info.java
+info.api.exception.invalid.format=Invalid format {0}, currently supported formats are YAML and JSON.
+info.api.exception=Supported format definition not found.