Migrate to swagger v3 / openapi

- upgrade spring boot to 2.7.6 - add smoke test for the application - add openapi specs to the readme - slightly reorder dependencies, added junit, openapi, swaggerv3 mockito this also fixes #
marcoserafini2 · Dec 3, 2022 · dcf0d30 · dcf0d30
1 parent 45b9678
commit dcf0d30
Show file tree

Hide file tree

Showing 8 changed files with 145 additions and 67 deletions.
diff --git a/buildSrc/src/main/java/org/jodconverter/Deps.java b/buildSrc/src/main/java/org/jodconverter/Deps.java
@@ -18,7 +18,7 @@ public class Deps {
 
   // Spring Boot libraries
   // Latest version -> https://mvnrepository.com/artifact/org.springframework.boot/spring-boot
-  public static final String springBootVersion = "2.7.3";
+  public static final String springBootVersion = "2.7.6";
   public static final String springBootDependencies =
       "org.springframework.boot:spring-boot-dependencies:" + springBootVersion;
   public static final String springBootStarter = "org.springframework.boot:spring-boot-starter";

diff --git a/jodconverter-samples/jodconverter-sample-rest/README.md b/jodconverter-samples/jodconverter-sample-rest/README.md
@@ -26,4 +26,10 @@ Once started, use your favorite browser and visit this page:
 http://localhost:8080/swagger-ui.html
 ```
 
+You can also ge the openapi specs from 
+
+```
+http://localhost:8080/rest/api
+```
+
 Happy conversions!!
diff --git a/jodconverter-samples/jodconverter-sample-rest/build.gradle b/jodconverter-samples/jodconverter-sample-rest/build.gradle
@@ -1,17 +1,21 @@
+import org.jodconverter.Deps
+
 plugins {
     id 'java'
     id 'eclipse'
     id 'idea'
     id 'war'
-    id 'org.springframework.boot' version '2.2.4.RELEASE'
+    id 'org.springframework.boot' version '2.7.6'
 }
 
 group = 'org.jodconverter'
 description = 'JODConverter - Sample Rest Web Api'
 
 ext {
     commonsIoVersion = '2.11.0'
-    swaggerVersion = '3.0.0'
+    mockitoVersion = '4.9.0'
+    swaggerVersion = "2.2.7"
+    openapiVersion = "1.6.13"
 }
 
 java {
@@ -25,13 +29,28 @@ repositories {
 
 
 dependencies {
-    implementation project(":jodconverter-local")
-    implementation project(":jodconverter-spring-boot-starter")
-
-    implementation "commons-io:commons-io:$commonsIoVersion"
-
-    implementation "org.springframework.boot:spring-boot-starter-web"
-    implementation "org.glassfish.jaxb:jaxb-runtime"
-    implementation "io.springfox:springfox-swagger2:$swaggerVersion"
-    implementation "io.springfox:springfox-swagger-ui:$swaggerVersion"
+    implementation (
+            project(":jodconverter-local"),
+            project(":jodconverter-spring-boot-starter"),
+
+            "commons-io:commons-io:$commonsIoVersion",
+            "org.springframework.boot:spring-boot-starter-web",
+            "org.glassfish.jaxb:jaxb-runtime",
+            "org.springdoc:springdoc-openapi-webmvc-core:${openapiVersion}",
+            "org.springdoc:springdoc-openapi-ui:${openapiVersion}",
+            "io.swagger.core.v3:swagger-annotations:${swaggerVersion}"
+    )
+
+    testRuntimeOnly("org.junit.jupiter:junit-jupiter-engine")
+
+
+    testImplementation(Deps.springBootStarterTest) {
+        exclude group: "org.junit.vintage", module: "junit-vintage-engine"
+    }
+
+    testImplementation(
+            "org.junit.jupiter:junit-jupiter-api",
+            "org.junit.jupiter:junit-jupiter-params",
+            Deps.mockito,
+    )
 }
diff --git a/...converter-sample-rest/src/main/java/org/jodconverter/sample/rest/ConverterController.java b/...converter-sample-rest/src/main/java/org/jodconverter/sample/rest/ConverterController.java
@@ -25,11 +25,10 @@
 import java.util.Locale;
 import java.util.Map;
 
-import io.swagger.annotations.Api;
-import io.swagger.annotations.ApiOperation;
-import io.swagger.annotations.ApiParam;
-import io.swagger.annotations.ApiResponse;
-import io.swagger.annotations.ApiResponses;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.Parameter;
+import io.swagger.v3.oas.annotations.responses.ApiResponse;
+import io.swagger.v3.oas.annotations.responses.ApiResponses;
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
 import org.springframework.http.HttpHeaders;
@@ -61,7 +60,6 @@
  */
 @Controller
 @RequestMapping("/lool/convert-to")
-@Api("Conversion Operations which emulate a LibreOffice Online server conversion capabilities.")
 public class ConverterController {
 
   private static final Logger LOGGER = LoggerFactory.getLogger(ConverterController.class);
@@ -88,46 +86,60 @@ public ConverterController(final OfficeManager officeManager) {
     this.officeManager = officeManager;
   }
 
-  @ApiOperation(
-      "Converts the incoming document to the specified format (provided as request param)"
-          + " and returns the converted document.")
+  @Operation(
+      summary =
+          "Converts the incoming document to the specified format (provided as request param)"
+              + " and returns the converted document.")
   @ApiResponses(
       value = {
-        @ApiResponse(code = 200, message = "Document converted successfully."),
-        @ApiResponse(code = 400, message = "The input document or output format is missing."),
-        @ApiResponse(code = 500, message = "An unexpected error occurred.")
+        @ApiResponse(responseCode = "200", description = "Document converted successfully."),
+        @ApiResponse(
+            responseCode = "400",
+            description = "The input document or output format is missing."),
+        @ApiResponse(responseCode = "500", description = "An unexpected error occurred.")
       })
   @PostMapping(produces = MediaType.APPLICATION_OCTET_STREAM_VALUE)
   /* default */ Object convertToUsingParam(
-      @ApiParam(value = "The input document to convert.", required = true) @RequestParam("data")
+      @Parameter(description = "The input document to convert.", required = true)
+          @RequestParam("data")
           final MultipartFile inputFile,
-      @ApiParam(value = "The document format to convert the input document to.", required = true)
+      @Parameter(
+              description = "The document format to convert the input document to.",
+              required = true)
           @RequestParam(name = "format")
           final String convertToFormat,
-      @ApiParam("The custom options to apply to the conversion.") @RequestParam(required = false)
+      @Parameter(description = "The custom options to apply to the conversion.")
+          @RequestParam(required = false)
           final Map<String, String> parameters) {
 
     LOGGER.debug("convertUsingRequestParam > Converting file to {}", convertToFormat);
     return convert(inputFile, convertToFormat, parameters);
   }
 
-  @ApiOperation(
-      "Converts the incoming document to the specified format (provided as path param)"
-          + " and returns the converted document.")
+  @Operation(
+      summary =
+          "Converts the incoming document to the specified format (provided as path param)"
+              + " and returns the converted document.")
   @ApiResponses(
       value = {
-        @ApiResponse(code = 200, message = "Document converted successfully."),
-        @ApiResponse(code = 400, message = "The input document or output format is missing."),
-        @ApiResponse(code = 500, message = "An unexpected error occurred.")
+        @ApiResponse(responseCode = "200", description = "Document converted successfully."),
+        @ApiResponse(
+            responseCode = "400",
+            description = "The input document or output format is missing."),
+        @ApiResponse(responseCode = "500", description = "An unexpected error occurred.")
       })
   @PostMapping(value = "/{format}", produces = MediaType.APPLICATION_OCTET_STREAM_VALUE)
   /* default */ Object convertToUsingPath(
-      @ApiParam(value = "The input document to convert.", required = true) @RequestParam("data")
+      @Parameter(description = "The input document to convert.", required = true)
+          @RequestParam("data")
           final MultipartFile inputFile,
-      @ApiParam(value = "The document format to convert the input document to.", required = true)
+      @Parameter(
+              description = "The document format to convert the input document to.",
+              required = true)
           @PathVariable(name = "format")
           final String convertToFormat,
-      @ApiParam("The custom options to apply to the conversion.") @RequestParam(required = false)
+      @Parameter(description = "The custom options to apply to the conversion.")
+          @RequestParam(required = false)
           final Map<String, String> parameters) {
 
     LOGGER.debug("convertUsingPathVariable > Converting file to {}", convertToFormat);

diff --git a/...ter-sample-rest/src/main/java/org/jodconverter/sample/rest/SpringBootRestApplication.java b/...ter-sample-rest/src/main/java/org/jodconverter/sample/rest/SpringBootRestApplication.java
@@ -19,19 +19,15 @@
 
 package org.jodconverter.sample.rest;
 
-import java.util.Collections;
+import java.util.*;
 
+import io.swagger.v3.oas.models.OpenAPI;
+import io.swagger.v3.oas.models.info.*;
+import io.swagger.v3.oas.models.servers.Server;
 import org.springframework.boot.SpringApplication;
 import org.springframework.boot.autoconfigure.SpringBootApplication;
 import org.springframework.context.annotation.Bean;
 import org.springframework.context.annotation.Configuration;
-import springfox.documentation.builders.PathSelectors;
-import springfox.documentation.builders.RequestHandlerSelectors;
-import springfox.documentation.service.ApiInfo;
-import springfox.documentation.service.Contact;
-import springfox.documentation.spi.DocumentationType;
-import springfox.documentation.spring.web.plugins.Docket;
-import springfox.documentation.swagger2.annotations.EnableSwagger2;
 
 /** Main application. */
 @SpringBootApplication
@@ -46,32 +42,31 @@ public static void main(final String[] args) {
     SpringApplication.run(SpringBootRestApplication.class, args);
   }
 
-  /** Swagger configuration. */
   @Configuration
-  @EnableSwagger2
-  /* default */ static class SwaggerConfig {
+  static class OpenApiConfig {
 
     @Bean
-    /* default */ Docket api() {
-      return new Docket(DocumentationType.SWAGGER_2)
-          .useDefaultResponseMessages(false)
-          .select()
-          .apis(RequestHandlerSelectors.basePackage("org.jodconverter.sample.rest"))
-          .paths(PathSelectors.regex("/lool/convert-to.*"))
-          .build()
-          .apiInfo(apiInfo());
-    }
+    public OpenAPI openAPI() {
+      final Info info =
+          new Info()
+              .title("JODConverter REST API")
+              .description(
+                  "JODConverter REST API for Remote conversion. JODConverter automates conversions between office document formats using LibreOffice or Apache OpenOffice.")
+              .version("0.1")
+              .termsOfService("Terms of service")
+              .license(
+                  new License()
+                      .name("Apache License Version 2.0")
+                      .url("https://www.apache.org/licenses/LICENSE-2.0"));
+
+      Server apiServer = new Server();
+      apiServer.setDescription("local");
+      apiServer.setUrl("/");
+
+      List<Server> servers = new ArrayList<>();
+      servers.add(apiServer);
 
-    private ApiInfo apiInfo() {
-      return new ApiInfo(
-          "JODConverter REST API",
-          "JODConverter REST API for Remote conversion. JODConverter automates conversions between office document formats using LibreOffice or Apache OpenOffice.",
-          "0.1",
-          "Terms of service",
-          new Contact("John Doe", "www.johndoe.org", "johndoe@company.com"),
-          "Apache License Version 2.0",
-          "https://www.apache.org/licenses/LICENSE-2.0",
-          Collections.emptyList());
+      return new OpenAPI().servers(servers).info(info);
     }
   }
 }
diff --git a/jodconverter-samples/jodconverter-sample-rest/src/main/resources/application.yml b/jodconverter-samples/jodconverter-sample-rest/src/main/resources/application.yml
@@ -9,6 +9,16 @@ spring:
   application:
     name: JODConverter Sample Rest Api
 
+springdoc:
+  show-actuator: false
+  api-docs:
+    path: /rest/api
+    groups:
+      enabled: true
+  swagger-ui:
+    enabled: true
+    path: /swagger-ui.html
+
 jodconverter:
   local:
     enabled: true

diff --git a/...sample-rest/src/test/java/org/jodconverter/sample/rest/SpringBootRestApplicationTest.java b/...sample-rest/src/test/java/org/jodconverter/sample/rest/SpringBootRestApplicationTest.java
@@ -0,0 +1,36 @@
+/*
+ * Copyright 2004 - 2012 Mirko Nasato and contributors
+ *           2016 - 2020 Simon Braconnier and contributors
+ *
+ * This file is part of JODConverter - Java OpenDocument Converter.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.jodconverter.sample.rest;
+
+import static org.assertj.core.api.AssertionsForInterfaceTypes.assertThat;
+
+import org.junit.jupiter.api.Test;
+import org.springframework.boot.test.context.SpringBootTest;
+
+@SpringBootTest
+class SpringBootRestApplicationTest {
+  @Test
+  void shouldStartApplication() {
+    // we do not need to do anything else here. This is just a smoke test verifying the entire boot
+    // configuration works,
+    // all beans can be wired and the app starts as expected
+    assertThat("smoke test").isEqualTo("smoke test");
+  }
+}
diff --git a/jodconverter-samples/jodconverter-sample-spring-boot/build.gradle b/jodconverter-samples/jodconverter-sample-spring-boot/build.gradle
@@ -3,7 +3,7 @@ plugins {
     id 'eclipse'
     id 'idea'
     id 'war'
-    id 'org.springframework.boot' version '2.7.3'
+    id 'org.springframework.boot' version '2.7.6'
 }
 
 group = 'org.jodconverter'