problem-spring-web/problem-spring-web at main

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 Spring Boot, add the following dependency to your project:

<dependency>
    <groupId>org.zalando</groupId>
    <artifactId>problem-spring-web</artifactId>
    <version>${problem-spring-web.version}</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 {

}