Using the Quarkus extension for the Spring Web API
Abstract
Part I. Using the Quarkus extension for the Spring Web API Copy linkLink copied to clipboard!
As an application developer, you can use Spring Web annotations to define RESTful services in your Quarkus application.
Making open source more inclusive Copy linkLink copied to clipboard!
Red Hat is committed to replacing problematic language in our code, documentation, and web properties. We are beginning with these four terms: master, slave, blacklist, and whitelist. Because of the enormity of this endeavor, these changes will be implemented gradually over several upcoming releases. For more details, see our CTO Chris Wright’s message.
Quarkus provides a compatibility layer for using annotations from Spring Web to define REST endpoints for your application. This functionality is provided by the quarkus-spring-web extension as an alternative to using the default JAX-RS annotations to define your REST endpoints.
The Spring compatibility layer in Quarkus does not start a Spring Application Context or execute any infrastructure classes that are provided by Spring (for example, org.springframework.beans.factory.config.BeanPostProcessor) when you start your application. Quarkus can only read metadata from Spring classes and annotations and parse user code method return types and parameter types that are specific to Spring. However, when you add arbitrary libraries that are part of Spring Framework to your Quarkus application, such libraries will not function properly because Quarkus is not designed to use them.
You can create the example that uses the Quarkus extension for the Spring Web API by following this guide or you can download and view the completed example. To view the completed Quarkus Spring Web example, download it as an archive or clone the Quarkus examples Git repository. You can find the Spring Web example in the spring-web-quickstart directory.
Chapter 1. Prerequisites Copy linkLink copied to clipboard!
-
Have OpenJDK 11 installed and the
JAVA_HOMEenvironment variable set to match the path to the directory in which OpenJDK is installed on your system. - Have Apache Maven 3.8.1 or higher installed.
Chapter 2. Creating the Spring Web example Maven project Copy linkLink copied to clipboard!
You can create a new Quarkus project, automatically generate the REST controller class, and add the quarkus-spring-web dependency with a single command by using the Quarkus Maven plugin. You can also update the pom.xml file and create the REST controller class and the REST controller test class manually.
Procedure
Use one of the following approaches to create your Quarkus Spring Web example Maven project:
If you do not have a Maven project, you can create a new Maven project by using the Quarkus Maven plugin. Enter the following command to complete the following actions:
- Create the Maven project directory structure
-
Create the
org.acme.spring.web.GreetingControllerclass that defines a REST endpoint for your application Import the
quarkus-spring-webextensionYou must replace
<project_name>with the name of the directory that contains your project files.Copy to Clipboard Copied! Toggle word wrap Toggle overflow
-
If you already have a Quarkus Maven project, you must add the
quarkus-spring-webextension to it by using the command line:
Navigate to the root directory of your project. Enter the following command:
cd <project_name>
cd <project_name>Copy to Clipboard Copied! Toggle word wrap Toggle overflow Add the
quarkus-spring-webextension to thepom.xmlfile of your project. Enter the following command:./mvnw quarkus:add-extension -Dextensions="spring-web"
./mvnw quarkus:add-extension -Dextensions="spring-web"Copy to Clipboard Copied! Toggle word wrap Toggle overflow The following entry is added to your
pom.xmlfile:pom.xml
<dependency> <groupId>io.quarkus</groupId> <artifactId>quarkus-spring-web</artifactId> </dependency><dependency> <groupId>io.quarkus</groupId> <artifactId>quarkus-spring-web</artifactId> </dependency>Copy to Clipboard Copied! Toggle word wrap Toggle overflow
Chapter 3. Creating the main class and test class for GreetingController Copy linkLink copied to clipboard!
When you create your project on the command line, the Quarkus Maven plugin automatically generates the GreetingController class file with Spring Web annotations that defines the REST endpoint and a class file that contains the unit test for GreetingController.
Procedure
Create the
src/main/java/org/acme/spring/web/GreetingController.javafile that contains the following code.src/main/java/org/acme/spring/web/GreetingController.java
Copy to Clipboard Copied! Toggle word wrap Toggle overflow Create the
src/test/java/org/acme/spring/web/GreetingControllerTest.javafile that contains the following code.src/test/java/org/acme/spring/web/GreetingControllerTest.java
Copy to Clipboard Copied! Toggle word wrap Toggle overflow
Chapter 4. Compiling and starting your Spring Web example Copy linkLink copied to clipboard!
Compile and start your example application by using the Quarkus Maven Plugin. You can also compile and run your application as a native executable.
Procedure
Navigate to the root directory of your project. Enter the following command:
cd <project_name>
cd <project_name>Copy to Clipboard Copied! Toggle word wrap Toggle overflow Run the application in development mode by using the Quarkus Maven Plugin. Enter the following command:
./mvnw quarkus:dev
./mvnw quarkus:devCopy to Clipboard Copied! Toggle word wrap Toggle overflow Navigate to the
http://localhost:8080/greetingdirectory. Your browser displays the following message:Hello Spring
Hello SpringCopy to Clipboard Copied! Toggle word wrap Toggle overflow
Chapter 5. Configuring the GreetingController to return a JSON response Copy linkLink copied to clipboard!
The GreetingController that is automatically generated when you set up your Spring Web example is a simple endpoint that returns a text string as a response. In more complex applications, you might need to configure your REST controller to return a response in JSON format. The following example illustrates how you can configure a Spring RestController to return JSON content.
Procedure
Expand your
GreetingControllerclass as shown in the example. The expanded class returns a JSON-formatted response that contains a greeting and a name. To ensure that your configuration works correctly, you must import thePathVariableannotation class from Spring Web:src/main/java/org/acme/spring/web/GreetingController.java
Copy to Clipboard Copied! Toggle word wrap Toggle overflow When you make changes to your REST endpoint, you must update the class file that contains the unit tests for your REST endpoint:
src/test/java/org/acme/spring/web/GreetingControllerTest.java
Copy to Clipboard Copied! Toggle word wrap Toggle overflow NoteWhen 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.
Chapter 6. Enabling OpenAPI and Swagger-UI support in your Spring Web example Copy linkLink copied to clipboard!
You can add support for generating OpenAPI schema documents of your REST endpoints with Swagger-UI to your application by adding the quarkus-smallrye-openapi extension.
Procedure
Add the
quarkus-smallrye-openapiextension as a dependency of your Spring Web example. By adding the extension, you can generate a basic OpenAPI schema document from your REST Endpoints. Enter the following command:./mvnw quarkus:add-extension -Dextensions="io.quarkus:quarkus-smallrye-openapi"
./mvnw quarkus:add-extension -Dextensions="io.quarkus:quarkus-smallrye-openapi"Copy to Clipboard Copied! Toggle word wrap Toggle overflow The following dependency is added to your
pom.xml:pom.xml
<dependency> <groupId>io.quarkus</groupId> <artifactId>quarkus-smallrye-openapi</artifactId> </dependency><dependency> <groupId>io.quarkus</groupId> <artifactId>quarkus-smallrye-openapi</artifactId> </dependency>Copy to Clipboard Copied! Toggle word wrap Toggle overflow Obtain the schema document from the
/q/openapi. Enter the following command:curl http://localhost:8080/q/openapi
curl http://localhost:8080/q/openapiCopy to Clipboard Copied! Toggle word wrap Toggle overflow You receive a response with the generated OpenAPI schema document in YAML format:
Copy to Clipboard Copied! Toggle word wrap Toggle overflow
Chapter 7. Adding MicroProfile OpenAPI annotations to your REST controller code Copy linkLink copied to clipboard!
You can add MicroProfile OpenAPI annotations to your REST controller code to generate a more detailed OpenAPI schema for your REST endpoints.
Procedure
Add the
@OpenApiDefinitionannotation at the class level of yourGreetingController. Include the data that is shown in the annotation in the following example:Copy to Clipboard Copied! Toggle word wrap Toggle overflow Annotate your endpoint definitions by using the
@Tagannotation. Enter a name and a description for each endpoint:Copy to Clipboard Copied! Toggle word wrap Toggle overflow The data that you provided in the annotations appears in the generated OpenAPI schema:
Copy to Clipboard Copied! Toggle word wrap Toggle overflow
Chapter 8. Overview of Spring Web annotations supported in Quarkus Copy linkLink copied to clipboard!
The Spring compatibility layer in Quarkus supports a limited subset of features that Spring Web provides. Specifically, Quarkus supports only the REST-related annotations from Spring Web, for example, @RestController, but not @Controller.
Quarkus supports the following annotations from Spring Web:
Chapter 9. Overview of Spring Web annotations and their JAX-RS equivalents Copy linkLink copied to clipboard!
The following table shows how Spring Web annotations can be converted to JAX-RS annotations.
| Spring | JAX-RS | Notes |
|---|---|---|
|
|
No equivalent annotation in JAX-RS. Annotating a class with | |
|
|
| |
|
|
| |
|
|
| |
|
|
| |
|
|
| |
|
| No equivalent annotation in JAX-RS. Method parameters that correspond to the body of the request are handled in JAX-RS without requiring any annotation. | |
|
| No equivalent annotation in JAX-RS. | |
|
| No equivalent annotation in JAX-RS. | |
|
|
No equivalent annotation in JAX-RS. Exceptions are handled by implementing |
Chapter 10. Controller method parameter types supported in Quarkus Copy linkLink copied to clipboard!
In addition to the method parameters that can be annotated with the appropriate Spring Web annotations from the previous table, the following controller method parameter types are supported:
-
javax.servlet.http.HttpServletRequest -
javax.servlet.http.HttpServletResponse
For this to function, users must add the quarkus-undertow dependency.
Chapter 11. Controller method return types supported in Quarkus Copy linkLink copied to clipboard!
The Quarkus extension for Spring Web API supports the following method return types:
- Primitive types
- String (Used as a literal. Quarkus does not support Spring MVC view)
- POJO classes that are serialized using JSON
-
org.springframework.http.ResponseEntity
Chapter 12. Exception handler method parameter types supported in Quarkus Copy linkLink copied to clipboard!
The Quarkus extension for Spring Web API supports the following exception handler method parameter types:
-
An exception argument: declared as a general
Exceptionor as a more specific exception. This also serves as a mapping hint if the annotation itself does not specify the exception types using itsvalue(). -
Request objects or response objects or both (typically from the Servlet API): You can choose any specific request or response type, for example
ServletRequestorHttpServletRequest. To use the Servlet API, you must add thequarkus-undertowdependency to your project.
The order in which the types are listed is arbitrary and does not reflect the order of preference in which individual parameter types should be used.
Other parameter types that are mentioned in the Spring ExceptionHandler Java API documentation are not supported in Quarkus
Chapter 13. Exception handler method return types supported in Quarkus Copy linkLink copied to clipboard!
The Quarkus extension for Spring Web API supports the following method return types:
-
org.springframework.http.ResponseEntity -
java.util.Map
Other return types mentioned in the Spring ExceptionHandler Java API documentation are not supported in Quarkus.