Quarkus - Quarkus Extension for Spring Web API

While users are encouraged to use JAX-RS annotation for defining REST endpoints, Quarkus provides a compatibility layer for Spring Web in the form of the spring-web extension.

This guide explains how a Quarkus application can leverage the well known Spring Web annotations to define RESTful services.


To complete this guide, you need:

  • less than 15 minutes

  • an IDE

  • JDK 1.8+ installed with JAVA_HOME configured appropriately

  • Apache Maven 3.5.3+


We recommend that you follow the instructions in the next sections and create the application step by step. However, you can go right to the completed example.

Clone the Git repository: git clone https://github.com/quarkusio/quarkus-quickstarts.git, or download an archive.

The solution is located in the using-spring-web directory.

Creating the Maven project

First, we need a new project. Create a new project with the following command:

mvn io.quarkus:quarkus-maven-plugin:0.22.0:create \
    -DprojectGroupId=org.acme \
    -DprojectArtifactId=using-spring-web \
    -DclassName="org.acme.spring.web.GreetingController" \
    -Dpath="/greeting" \

This command generates a Maven project with a REST endpoint and imports the spring-web extension.


The Quarkus maven plugin automatically generated a controller with the Spring Web annotations to define our REST endpoint (instead of the JAX-RS ones used by default) The src/main/java/org/acme/spring/web/GreetingController.java file looks as follows:

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;
import org.springframework.web.bind.annotation.PathVariable;

public class GreetingController {

    public String hello() {
        return "hello";


Note that a test for the controller has been created as well:

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;

public class GreetingControllerTest {

    public void testHelloEndpoint() {


Package and run the application

Run the application with: ./mvnw compile quarkus:dev. Open your browser to http://localhost:8080/greeting.

The result should be: {"message": "hello"}.

Run the application as a native executable

You can of course create a native image using the instructions of the Building a native executable guide.

Supported Spring Web functionalities

Quarkus currently supports a subset of the functionalities that Spring Web provides. More specifically Quarkus supports the REST related features of Spring Web (think of @RestController instead of @Controller).


The table below summarizes the supported annotations:

Table 1. Supported Spring Web annotation
Name Comments
















Can only be used in a @RestControllerAdvice class, not on a per-controller basis


Only the @ExceptionHandler capability is supported

Controller method return types

The following method return types are supported:

  • Primitive types

  • String (which will be used as a literal, no Spring MVC view support is provided)

  • POJO classes which will be serialized via JSON

  • org.springframework.http.ResponseEntity

Controller method return types

In addition to the method parameters that can be annotated with the appropriate Spring Web annotations from the previous table, javax.servlet.http.HttpServletRequest and javax.servlet.http.HttpServletResponse are also supported.

Important Technical Note

Please note that the Spring support in Quarkus does not start a Spring Application Context nor are any Spring infrastructure classes run. Spring classes and annotations are only used for reading metadata and / or are used as user code method return types or parameter types. What that means for end users, is that adding arbitrary Spring libraries will not have any effect. Moreover Spring infrastructure classes (like org.springframework.beans.factory.config.BeanPostProcessor for example) will not be executed.

More Spring guides

Quarkus support has more Spring compatibility features. See the following guides for more details: