Package com.atlassian.oai.validator

Class OpenApiInteractionValidator.Builder

java.lang.Object
com.atlassian.oai.validator.OpenApiInteractionValidator.Builder
Enclosing class:
OpenApiInteractionValidator
public static class OpenApiInteractionValidator.Builder extends Object
A builder used to createFor configured instances of the OpenApiInteractionValidator.

  • Constructor Details

    • Builder

      public Builder()

  • Method Details

    • withSwaggerJsonUrl

      @Deprecated public OpenApiInteractionValidator.Builder withSwaggerJsonUrl(String specUrlOrPayload)
      Deprecated.
      use withApiSpecification(String). This method will be removed in a future release.
      The location of the OpenAPI / Swagger specification to use in the validator, or the inline specification to use.

      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
     .withSwaggerJsonUrl("http://api.myservice.com/swagger.json")

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

     // Create from a classpath resource in the /api package
     .withSwaggerJsonUrl("/api/swagger.json");
      Parameters:
      specUrlOrPayload - The OpenAPI / Swagger specification to use in the validator.
      Returns:
      this builder instance.

    • withApiSpecification

      @Deprecated public OpenApiInteractionValidator.Builder withApiSpecification(String specUrlOrPayload)
      Deprecated.
      Use withInlineApiSpecification(String) or withApiSpecificationUrl(String)
      The location of the OpenAPI / Swagger specification to use in the validator, or the inline specification to use.

      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
     .withSwaggerJsonUrl("http://api.myservice.com/swagger.json")

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

     // Create from a classpath resource in the /api package
     .withSwaggerJsonUrl("/api/swagger.json");
      Parameters:
      specUrlOrPayload - The OpenAPI / Swagger specification to use in the validator.
      Returns:
      this builder instance.

    • withInlineApiSpecification

      public OpenApiInteractionValidator.Builder withInlineApiSpecification(String inlineSpecPayload)
      The inline API specification to use.

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

      Parameters:
      inlineSpecPayload - The OpenAPI / Swagger specification to use in the validator.
      Returns:
      this builder instance.

    • withApiSpecificationUrl

      public OpenApiInteractionValidator.Builder withApiSpecificationUrl(String specUrl)
      The location of the OpenAPI / Swagger specification to use in the validator.

      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
     .withSwaggerJsonUrl("http://api.myservice.com/swagger.json")

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

     // Create from a classpath resource in the /api package
     .withSwaggerJsonUrl("/api/swagger.json");
      Parameters:
      specUrl - The OpenAPI / Swagger specification to use in the validator.
      Returns:
      this builder instance.

    • withApi

      public OpenApiInteractionValidator.Builder withApi(io.swagger.v3.oas.models.OpenAPI api)

    • withBasePathOverride

      public OpenApiInteractionValidator.Builder withBasePathOverride(String basePathOverride)
      An optional basepath override to override the one defined in the OpenAPI / Swagger spec.

      This can be useful if e.g. your Swagger specification has been created for a public URL but you are validating requests against an internal URL where the URL paths differ.

      Parameters:
      basePathOverride - An optional basepath override to override the one defined in the spec.
      Returns:
      this builder instance.

    • withLevelResolver

      public OpenApiInteractionValidator.Builder withLevelResolver(LevelResolver levelResolver)
      The resolver to use for resolving the level of validation messages (ERROR, WARN, IGNORE etc.).

      This can be used to get fine-grained control over validation behaviour (e.g. what level to emit message at, which validations to ignore etc.).

      If not provided, a default resolver will be used that resolves all message to ERROR.

      Parameters:
      levelResolver - The resolver to use for resolving validation message levels.
      Returns:
      this builder instance.

    • withWhitelist

      public OpenApiInteractionValidator.Builder withWhitelist(ValidationErrorsWhitelist whitelist)
      A whitelist for error messages. Whitelisted error messages will still be returned, but their level will be changed to IGNORE and additional information about whitelisting will be added.
      Parameters:
      whitelist - The whitelist to use.
      Returns:
      this builder instance

    • withAuthHeaderData

      public OpenApiInteractionValidator.Builder withAuthHeaderData(String key, String value)
      An optional key value header to add to the OpenAPI / Swagger spec retrieval request.

      This is necessary if e.g. your specification is retrieved from a remote host and the path to retrieve is secured by an api key in the request header.

      Parameters:
      key - A key name to add as request header key.
      value - (Optional) A value to add as request header value for the given key.
      Returns:
      this builder instance.

    • withCustomRequestValidation

      public OpenApiInteractionValidator.Builder withCustomRequestValidation(CustomRequestValidator validator)
      An optional custom request validation step. Possible usages include validation of vendor specific extensions.
      Parameters:
      validator - The validator to apply
      Returns:
      this builder instance

    • withCustomResponseValidation

      public OpenApiInteractionValidator.Builder withCustomResponseValidation(CustomResponseValidator validator)
      An optional custom response validation step. Possible usages include validation of vendor specific extensions.
      Parameters:
      validator - The validator to apply
      Returns:
      this builder instance

    • withResolveRefs

      public OpenApiInteractionValidator.Builder withResolveRefs(boolean resolveRefs)
      Sets the resolve and resolveFully flags on the ParseOptions supplied to the underlying OpenAPIParser. Useful if you need to control whether the parser resolves refs prior to validation. Default is true.

      If additional parse options are needed use withParseOptions(ParseOptions) to supply a fully-constructed instance.

      Returns:
      this builder instance
      See Also:

    • withResolveCombinators

      public OpenApiInteractionValidator.Builder withResolveCombinators(boolean resolveCombinators)
      Sets the resolveCombinators flag on the ParseOptions supplied to the underlying OpenAPIParser. Useful when using allOf composition to avoid the problems with additionalProperties.

      If additional parse options are needed use withParseOptions(ParseOptions) to supply a fully-constructed instance.

      Returns:
      this builder instance
      See Also:

    • withParseOptions

      public OpenApiInteractionValidator.Builder withParseOptions(io.swagger.v3.parser.core.models.ParseOptions parseOptions)
      Optionally supply parse options to control the behavior of the underlying OpenAPIParser parser.

      Sensible defaults are provided, but this can be useful if you need more fine-grained control over the behavior. One example use case is to resolve schema combinators (allOf etc) to flatten the schema prior to validation to avoid some of the problems with allOf and additionalProperties

      The defaults used are:

      • resolve = true
      • resolveFully = true
      • resolveCombinators = false
      • flatten = false
      Parameters:
      parseOptions - Parse options to replace the defaults
      Returns:
      this builder instance

    • withSchemaFactorySupplier

      public OpenApiInteractionValidator.Builder withSchemaFactorySupplier(Supplier<com.github.fge.jsonschema.main.JsonSchemaFactory> schemaFactorySupplier)
      Optionally supply a function that returns a JsonSchemaFactory to use.

      Defaults to SwaggerV20Library's `schemaFactory`, but this can be useful if you have additional extensions to add to Library.

      Parameters:
      schemaFactorySupplier - A supplier function that returns a JsonSchemaFactory.
      Returns:
      this builder instance

    • withSchemaValidationConfiguration

      public OpenApiInteractionValidator.Builder withSchemaValidationConfiguration(ValidationConfiguration validationConfiguration)
      Optionally supply a configuration to configure the following aspects of validation:
      Parameters:
      validationConfiguration - The configuration for OpenApi validation.
      Returns:
      this builder instance

    • withStrictOperationPathMatching

      public OpenApiInteractionValidator.Builder withStrictOperationPathMatching()
      Optionally enable strict operation path matching. If enabled, a trailing slash indicates a different path than without. Defaults to false.
      Returns:
      this builder instance

    • build

      public OpenApiInteractionValidator build()
      Build a configured OpenApiInteractionValidator instance with the values collected in this builder.
      Returns:
      The configured OpenApiInteractionValidator instance.
      Throws:
      IllegalArgumentException - if the provided specUrlOrPayload is empty
      OpenApiInteractionValidator.ApiLoadException - if there was a problem loading the API spec