README.md

OpenAPI Request Validator - Spring Web MVC 7+

Integrations between the OpenAPI Request Validator and the Spring Web MVC framework.

This module includes an OpenApiValidationFilter and an OpenApiValidationInterceptor that can be used to add request and / or response validation to a REST web service utilizing Spring WebMVC 7 or later, including Spring Boot Starter applications utilizing Spring MVC (e.g. spring-boot-starter-web-services or spring-boot-starter-web).

In case of invalid requests against the REST web service an InvalidRequestException is thrown containing the ValidationReport.
In case of invalid responses coming from the REST web service an InvalidResponseException is thrown containing the ValidationReport.

This module is compatible with Spring 7+, Spring Boot 4+ and the Jakarta namespace. For use with older versions, review past releases of this library.

Usage

Adding the dependency

Add this dependency to your project.

e.g. for Maven in your pom.xml:

<dependency>
    <groupId>com.atlassian.oai</groupId>
    <artifactId>openapi-request-validator-spring-webmvc</artifactId>
    <version>${openapi-request-validator.version}</version>
</dependency>

Configuration

The following property is necessary to receive the error message in case of validation errors:

server.error.include-message=always

If this property is not set the client will receive an InvalidRequestException or InvalidResponseException without knowing what is wrong with the request / response as the message field will be missing.

Adding filter and interceptor

Add this configuration to your application.

import com.atlassian.oai.validator.springmvc.OpenApiValidationFilter;
import com.atlassian.oai.validator.springmvc.OpenApiValidationInterceptor;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.context.annotation.Bean;
import org.springframework.core.io.Resource;
import org.springframework.core.io.support.EncodedResource;
import org.springframework.web.servlet.config.annotation.InterceptorRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;

import jakarta.servlet.Filter;
import java.io.IOException;
import java.nio.charset.StandardCharsets;

@Configuration
public class OpenApiValidationConfig {
    @Bean
    public Filter validationFilter() {
        return new OpenApiValidationFilter(
                true, // enable request validation
                true  // enable response validation
        );
    }

    @Bean
    public WebMvcConfigurer addOpenApiValidationInterceptor(@Value("classpath:api-spring-test.json") final Resource apiSpecification) throws IOException {
        final EncodedResource specResource = new EncodedResource(openApiSpecification, StandardCharsets.UTF_8);
        final OpenApiValidationInterceptor openApiValidationInterceptor = new OpenApiValidationInterceptor(encodedResource);
        return new WebMvcConfigurer() {
            @Override
            public void addInterceptors(final InterceptorRegistry registry) {
                registry.addInterceptor(openApiValidationInterceptor);
            }
        };
    }
}

To get better control over the validation a custom OpenApiInteractionValidator can be used.

    @Bean
    public WebMvcConfigurer addOpenApiValidationInterceptor(@Value("${open.api.spec.url}") final Resource specificationUrl) throws IOException {
        final OpenApiInteractionValidator validator = OpenApiInteractionValidator
                .createForSpecificationUrl(specificationUrl)
                .withLevelResolver(SpringMVCLevelResolverFactory.create())
                .withBasePathOverride("/v1")
                .build();
        final OpenApiValidationInterceptor openApiValidationInterceptor = new OpenApiValidationInterceptor(validator);
        return new WebMvcConfigurer() {
            @Override
            public void addInterceptors(final InterceptorRegistry registry) {
                registry.addInterceptor(openApiValidationInterceptor);
            }
        };
    }

See the OpenAPI Request Validator - Core for more information on customizing the validator.

You might want to add logging for the package: com.atlassian.oai.validator.springmvc

Example

See the example tests for working examples.

• Simple — shows how to add the OpenAPI validation filter and interceptor to a Spring WebMVC application.
• Exception handler — shows how to add an ExceptionHandler to map InvalidRequestException and InvalidResponseException to a custom response.
• Request logging — shows how to add custom request logging before each validation using a custom OpenApiInteractionValidator.
• Async — shows how to use validation in an async request-processing context.

Limitations

A mapped Controller \ RESTController method might throw an exception, which will be mapped by Spring to a generic error response. Those error responses will not be validated.