Package com.atlassian.oai.validator

Class OpenApiInteractionValidator

java.lang.Object

com.atlassian.oai.validator.OpenApiInteractionValidator

public class OpenApiInteractionValidator
extends Object

Validates a HTTP interaction (request/response pair) with a Swagger v2 / OpenAPI v3 specification.

Validation errors are provided in a @ValidationReport that can be used to inspect the failures.

New instances should be created via the createFor(String) method.

See Also:

• createFor(String)

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static class	OpenApiInteractionValidator.ApiLoadException	An exception thrown when the OpenApiInteractionValidator is unable to load a given API spec
static class	OpenApiInteractionValidator.Builder	A builder used to createFor configured instances of the OpenApiInteractionValidator.
static class	OpenApiInteractionValidator.SpecSource	Holds the source location for an API specification.

Method Summary

Modifier and Type	Method	Description
static OpenApiInteractionValidator.Builder	createFor(io.swagger.v3.oas.models.OpenAPI api)	Create a new instance using a parsed API specification.
static OpenApiInteractionValidator.Builder	createFor(String specUrlOrPayload)	Create a new instance using the OpenAPI / Swagger specification at the given location OR an actual specification payload.
static OpenApiInteractionValidator.Builder	createForInlineApiSpecification(String specAsString)	Create a new instance using given the OpenAPI / Swagger specification.
static OpenApiInteractionValidator.Builder	createForSpecificationUrl(String specUrl)	Create a new instance using the OpenAPI / Swagger specification at the given location.
ValidationReport	validate(Request request, Response response)	Validate the given request/response against the API.
ValidationReport	validateRequest(Request request)	Validate the given request against the API.
ValidationReport	validateResponse(String path, Request.Method method, Response response)	Validate the given response against the API.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Details

createFor

public static OpenApiInteractionValidator.Builder createFor(@Nonnull
 String specUrlOrPayload)

Create a new instance using the OpenAPI / Swagger specification at the given location OR an actual specification payload.

Supports both Swagger v2 and OpenAPI v3 specifications, in both JSON and YAML formats.

The URL can be an absolute HTTP/HTTPS URL, a File URL or a classpath location (without the classpath: scheme).

For example:

     // Create from a publicly hosted HTTP location
     .createFor("http://api.myservice.com/swagger.json")

     // Create from a file on the local filesystem
     .createFor("file://Users/myuser/tmp/api.yaml");

     // Create from a classpath resource in the /api package
     .createFor("/api/swagger.json");

     // Create from an OpenAPI / Swagger payload
     .createFor("{\"swagger\": \"2.0\", ...}")
 

Note: This method may log exceptions during normal operation. To avoid this, consider using createForInlineApiSpecification(String) or createForSpecificationUrl(String) instead. This method may be deprecated in the future.

Parameters:

specUrlOrPayload - The location of the OpenAPI / Swagger specification to use in the validator, or the inline specification to use.

Returns:

A new builder instance to use for creating and configuring OpenApiInteractionValidator instances.

See Also:

• createForInlineApiSpecification(String)
• createForSpecificationUrl(String)

createForInlineApiSpecification

public static OpenApiInteractionValidator.Builder createForInlineApiSpecification(@Nonnull
 String specAsString)

Create a new instance using given the OpenAPI / Swagger specification.

Supports both Swagger v2 and OpenAPI v3 specifications, in both JSON and YAML formats.

Parameters:

specAsString - The OpenAPI / Swagger specification to use in the validator

Returns:

A new builder instance to use for creating and configuring OpenApiInteractionValidator instances.

createForSpecificationUrl

public static OpenApiInteractionValidator.Builder createForSpecificationUrl(@Nonnull
 String specUrl)

Create a new instance using the OpenAPI / Swagger specification at the given location.

Supports both Swagger v2 and OpenAPI v3 specifications, in both JSON and YAML formats.

The URL can be an absolute HTTP/HTTPS URL, a File URL or a classpath location (without the classpath: scheme).

For example:

     // Create from a publicly hosted HTTP location
     .createFor("http://api.myservice.com/swagger.json")

     // Create from a file on the local filesystem
     .createFor("file://Users/myuser/tmp/api.yaml");

     // Create from a classpath resource in the /api package
     .createFor("/api/swagger.json");

     // Create from an OpenAPI / Swagger payload
     .createFor("{\"swagger\": \"2.0\", ...}")
 

Parameters:

specUrl - The location of the OpenAPI / Swagger specification to use in the validator

Returns:

A new builder instance to use for creating and configuring OpenApiInteractionValidator instances.

createFor

public static OpenApiInteractionValidator.Builder createFor(@Nonnull
 io.swagger.v3.oas.models.OpenAPI api)

Create a new instance using a parsed API specification.

Parameters:

api - The API specification to use for validation

Returns:

A new builder instance to use for creating and configuring OpenApiInteractionValidator instances.

validate

@Nonnull
public ValidationReport validate(@Nonnull
 Request request,
 @Nonnull
 Response response)

Validate the given request/response against the API.

See class docs for more information on the validation performed.

Parameters:

request - The request to validate (required)

response - The response to validate (required)

Returns:

The outcome of the validation

validateRequest

@Nonnull
public ValidationReport validateRequest(@Nonnull
 Request request)

Validate the given request against the API.

See class docs for more information on the validation performed.

Parameters:

request - The request to validate (required)

Returns:

The outcome of the request validation

validateResponse

@Nonnull
public ValidationReport validateResponse(@Nonnull
 String path,
 @Nonnull
 Request.Method method,
 @Nonnull
 Response response)

Validate the given response against the API.

See class docs for more information on the validation performed.

Parameters:

path - The request path (required)

method - The request method (required)

response - The response to validate (required)

Returns:

The outcome of the response validation