README.md

Problem: Spring Web MVC

Installation

Spring boot

Add the starter module to your dependencies. That is all you will need to get a default working configuration (you can customize it by implementing advice traits):

<dependency>
    <groupId>org.zalando</groupId>
    <artifactId>problem-spring-web-starter</artifactId>
    <version>${problem-spring-web.version}</version>
</dependency>

The autoconfiguration will configure problem-spring-web to handle all problems plus Spring Security problems if Spring Security is detected

WebMVC

If you're not using problem-spring-web-starter, add the following dependencies to your project:

<dependency>
    <groupId>org.zalando</groupId>
    <artifactId>problem-spring-web</artifactId>
    <version>${problem-spring-web.version}</version>
</dependency>
<dependency>
    <groupId>org.zalando</groupId>
    <artifactId>jackson-datatype-problem</artifactId>
    <version>0.27.1</version>
</dependency>

Configuration

If not using the starter module, make sure you register the required modules with your ObjectMapper:

@Bean
public ProblemModule problemModule() {
    return new ProblemModule();
}

@Bean
public ConstraintViolationProblemModule constraintViolationProblemModule() {
    return new ConstraintViolationProblemModule();
}

The following table shows all built-in advice traits:

Advice Trait	Produces
ProblemHandling
├──GeneralAdviceTrait
│   ├──ProblemAdviceTrait	depends
│   ├──ThrowableAdviceTrait	500 Internal Server Error
│   └── UnsupportedOperationAdviceTrait	501 Not Implemented
├──HttpAdviceTrait
│   ├──MethodNotAllowedAdviceTrait	405 Method Not Allowed
│   ├──NotAcceptableAdviceTrait	406 Not Acceptable
│   └──UnsupportedMediaTypeAdviceTrait	415 Unsupported Media Type
├──IOAdviceTrait
│   ├──MessageNotReadableAdviceTrait	400 Bad Request
│   ├──MultipartAdviceTrait	400 Bad Request
│   └──TypeMismatchAdviceTrait	400 Bad Request
├──NetworkAdviceTrait
│   └──SocketTimeoutAdviceTrait	504 Gateway Timeout
├──RoutingAdviceTrait
│   ├──MissingServletRequestParameterAdviceTrait	400 Bad Request
│   ├──MissingServletRequestPartAdviceTrait	400 Bad Request
│   ├──NoHandlerFoundAdviceTrait	404 Not Found
│   ├──NoSuchRequestHandlingMethodAdviceTrait	404 Not Found
│   └──ServletRequestBindingAdviceTrait	400 Bad Request
└──ValidationAdviceTrait
├──ConstraintViolationAdviceTrait	400 Bad Request
└──MethodArgumentNotValidAdviceTrait	400 Bad Request

You're free to use them either individually or in groups. Future versions of this library may add additional traits to groups. A typical usage would look like this:

@ControllerAdvice
class ExceptionHandling implements ProblemHandling {

}

The NoHandlerFoundAdviceTrait in addition also requires the following configuration:

spring:
  resources:
    add-mappings: false
  mvc:
    throw-exception-if-no-handler-found: true

If you're using Spring Boot, make sure you disable the ErrorMvcAutoConfiguration:

@EnableAutoConfiguration(exclude = ErrorMvcAutoConfiguration.class)

Security

If not using the starter module, the Spring Security integration requires additional steps:

@ControllerAdvice
class ExceptionHandling implements ProblemHandling, SecurityAdviceTrait {

}

@Configuration
@Import(SecurityProblemSupport.class)
public class SecurityConfiguration extends ResourceServerConfigurerAdapter {

    @Autowired
    private SecurityProblemSupport problemSupport;

    @Override
    public void configure(final HttpSecurity http) {
        http.exceptionHandling()
                .authenticationEntryPoint(problemSupport)
                .accessDeniedHandler(problemSupport);
    }

}

To return valid problem objects upon authentication exceptions, you will also need to implement the SecurityAdviceTrait, this is already sufficient:

@ControllerAdvice
public class SecurityExceptionHandler implements SecurityAdviceTrait {
}

Failsafe

The optional failsafe integration adds support for CircuitBreakerOpenException in the form of an advice trait:

@ControllerAdvice
class ExceptionHandling implements ProblemHandling, CircuitBreakerOpenAdviceTrait {

}

An open circuit breaker will be translated into a 503 Service Unavailable:

HTTP/1.1 503 Service Unavailable
Content-Type: application/problem+json

{
  "title": "Service Unavailable",
  "status": 503
}

Swagger/OpenAPI Request Validator

The optional integration for Atlassian's Swagger Request Validator adds support for invalid request/response exceptions as a dedicated advice trait:

@ControllerAdvice
class ExceptionHandling implements ProblemHandling, OpenApiValidationAdviceTrait {

}