Using the Quarkus extension for the Spring Web API

Procedure

1. Create the src/main/java/org/acme/spring/web/GreetingController.java file that contains the following code.

   src/main/java/org/acme/spring/web/GreetingController.java

   package org.acme.spring.web;
   
   import org.springframework.web.bind.annotation.GetMapping;
   import org.springframework.web.bind.annotation.RequestMapping;
   import org.springframework.web.bind.annotation.RestController;
   
   @RestController
   @RequestMapping("/greeting")
   public class GreetingController {
   
       @GetMapping
       public String hello() {
           return "Hello Spring";
       }
   }

2. Create the src/test/java/org/acme/spring/web/GreetingControllerTest.java file that contains the following code.

   src/test/java/org/acme/spring/web/GreetingControllerTest.java

   package org.acme.spring.web;
   
   import io.quarkus.test.junit.QuarkusTest;
   import org.junit.jupiter.api.Test;
   
   import static io.restassured.RestAssured.given;
   import static org.hamcrest.CoreMatchers.is;
   
   @QuarkusTest
   public class GreetingControllerTest {
   
       @Test
       public void testHelloEndpoint() {
           given()
             .when().get("/greeting")
             .then()
                .statusCode(200)
                .body(is("Hello Spring"));
       }
   
   }

Procedure

1. Navigate to the root directory of your project:

   cd <project_name>

2. Run the application in development mode using the Quarkus Maven Plugin:

   ./mvnw compile quarkus:dev

3. Navigate to http://localhost:8080/greeting Your browser displays the following message:

   Hello Spring

Procedure

1. Expand your GreetingController class as shown in the example. The expanded class returns a JSON-formatted response that contains a greeting and a name. Note, that you must import the PathVariable annotation class from Spring Web to ensure that your configuration works correctly:

   src/main/java/org/acme/spring/web/GreetingController.java

   import org.springframework.web.bind.annotation.GetMapping;
   import org.springframework.web.bind.annotation.PathVariable;
   import org.springframework.web.bind.annotation.RequestMapping;
   import org.springframework.web.bind.annotation.RestController;
   
   @RestController
   @RequestMapping("/greeting")
   public class GreetingController {
   
       @GetMapping
       public String hello() {
           return "hello";
       }
   
       @GetMapping("/{name}")
       public Greeting hello(@PathVariable(name = "name") String name) {
           return new Greeting("hello " + name);
       }
   
       public static class Greeting {
           private final String message;
   
           public Greeting(String message) {
               this.message = message;
           }
   
           public String getMessage(){
               return message;
           }
       }
   }

1. When you make changes to your REST endpoint, you must also update the class file that contains the unit tests for your REST endpoint:

   src/test/java/org/acme/spring/web/GreetingControllerTest.java

   package org.acme.spring.web;
   
   import io.quarkus.test.junit.QuarkusTest;
   import org.junit.jupiter.api.Test;
   
   import static io.restassured.RestAssured.given;
   import static org.hamcrest.CoreMatchers.is;
   
   @QuarkusTest
   public class GreetingControllerTest {
   
       @Test
       public void testHelloEndpoint() {
           given()
             .when().get("/greeting/quarkus")
             .then()
               .statusCode(200)
               .body("message", is("hello quarkus"));
       }
   
   }

   Note, that when you use the Spring Web compatibility layer in Quarkus, the com.fasterxml:jackson.core dependency is automatically added to the classpath of your application and configured.

Procedure

1. Enter the following command to add the quarkus-smallrye-openapi extension as a dependency of your Spring Web example. Adding the extension is enough to generate a basic OpenAPI schema document from your REST Endpoints:

   ./mvnw quarkus:add-extension -Dextensions="io.quarkus:quarkus-smallrye-openapi"

   Entering the command adds the following dependency to your pom.xml:

   pom.xml

   <dependency>
       <groupId>io.quarkus</groupId>
       <artifactId>quarkus-smallrye-openapi</artifactId>
   </dependency>

2. Enter the following command to obtain the schema document from the /q/openapi:

   curl http://localhost:8080/q/openapi

   You receive a response with the generated OpenAPI schema document in YAML format:

   ---
   openapi: 3.0.3
   info:
     title: Generated API
     version: "1.0"
   paths:
     /greeting:
       get:
         responses:
           "200":
             description: OK
             content:
               text/plain:
                 schema:
                   type: string
     /greeting/{name}:
       get:
         parameters:
         - name: name
           in: path
           required: true
           schema:
             type: string
         responses:
           "200":
             description: OK
             content:
               application/json:
                 schema:
                   $ref: '#/components/schemas/Greeting'
   components:
     schemas:
       Greeting:
         type: object
         properties:
           message:
             type: string

Procedure

1. Add the @OpenApiDefinition annotation at the class level of your GreetingController. Include the data that is shown in the example in the annotation:

   @OpenAPIDefinition(
       info = @Info(
           title="Greeting API",
           version = "1.0.1",
           contact = @Contact(
               name = "Greeting API Support",
               url = "http://exampleurl.com/contact",
               email = "techsupport@example.com"),
           license = @License(
               name = "Apache 2.0",
               url = "https://www.apache.org/licenses/LICENSE-2.0.html"))
   )

2. Annotate your endpoint definitions using the @Tag annotation. Give a name and a description for each endpoint:

   @Tag(name = "Hello", description = "Just say hello")
   @GetMapping(produces=MediaType.TEXT_PLAIN_VALUE)
   public String hello() {
       return "hello";
   }
   
   @GetMapping(value = "/{name}", produces=MediaType.APPLICATION_JSON_VALUE)
   @Tag(name = "Hello to someone", description = "Just say hello to someone")
   public Greeting hello(@PathVariable(name = "name") String name) {
       return new Greeting("hello " + name);
   }

   The data that you provided in the annotations appears in the generated OpenAPI schema:

   openapi: 3.0.3
   info:
     title: Greeting API
     contact:
       name: Greeting API Support
       url: http://exampleurl.com/contact
       email: techsupport@example.com
     license:
       name: Apache 2.0
       url: https://www.apache.org/licenses/LICENSE-2.0.html
     version: 1.0.1
   tags:
   - name: Hello
       description: Just say hello
   - name: Hello to someone
       description: Just say hello to someone
   paths:
     /greeting:
       get:
         tags:
         - Hello
         responses:
           '200':
             description: OK
             content:
               text/plain:
                 schema:
                   type: string
     /greeting/{name}:
       get:
         tags:
         - Hello to someone
         parameters:
         - name: name
           in: path
           required: true
           schema:
             type: string
         responses:
           '200':
             description: OK
             content:
               application/json:
                 schema:
                   $ref: '#/components/schemas/Greeting'
   
   components:
     schemas:
       Greeting:
         type: object
         properties:
           message:
             type: string