sbt-openapi-style-validator

An sbt plugin to support the OpenAPI Style Validator project.

Usage

Add to your project/plugins.sbt:

addSbtPlugin("net.rouly" % "sbt-openapi-style-validator" % "version")

Update your build.sbt:

enablePlugins(OpenApiStylePlugin)
openApiStyleSpec := file("openapi.yaml")

Invoke one of the provided tasks:

> openApiStyleValidate
> openApiStyleValidationResult

Configuration

You may specify openapi-style-validator settings either in a configuration file or directly in the sbt build definition using the provided keys.

Using a configuration file

Supported formats include Java properties, HOCON and JSON.

Specify the config file in build.sbt:

openApiStyleConfig := Some(file("openapi-style-validator.conf"))

Specify configurations in the config file:

validateNaming = true
pathNamingConvention = UnderscoreCase
// etc.

Keys are the same as in openapi-style-validator.

Directly in sbt

You may also specify configuration settings directly in build.sbt via the provided keys:

openApiStyleValidateNaming := Some(true)
openApiStylePathNamingConvention := Some(NamingConvention.UnderscoreCase)
// etc.

sbt keys

Key	Type	Description
openApiStyleConfig	SettingKey[Option[File]]	OpenAPI Style Validator configuration file. Defaults to None.
openApiStyleSpec	TaskKey[File]	OpenAPI specification file.
openApiStyleValidate	TaskKey[Unit]	Validates OpenAPI specification file: success or failure.
openApiStyleValidationResult	TaskKey[Seq[String]]	Validates OpenAPI specification file: evaluates to a list of detailed error messages.
openApiStyleValidatorParameters	SettingKey[ValidatorParameters]	OpenAPI Style Validator parameters, typically set using configuration keys or a configuration file.

The following configuration keys are supported:

Key	Type	Description
openApiStyleValidateInfoLicense	SettingKey[Option[Boolean]]	Ensures that there is a license section in the info section.
openApiStyleValidateInfoDescription	SettingKey[Option[Boolean]]	Ensures that there is a description attribute in the info section.
openApiStyleValidateInfoContact	SettingKey[Option[Boolean]]	Ensures that there is a contact section in the info section.
openApiStyleValidateOperationId	SettingKey[Option[Boolean]]	Ensures that there is an operation id for each operation.
openApiStyleValidateOperationDescription	SettingKey[Option[Boolean]]	Ensures that there is a description for each operation.
openApiStyleValidateOperationTag	SettingKey[Option[Boolean]]	Ensures that there is a tag for each operation.
openApiStyleValidateOperationSummary	SettingKey[Option[Boolean]]	Ensures that there is a summary for each operation.
openApiStyleValidateModelPropertiesExample	SettingKey[Option[Boolean]]	Ensures that the properties of the Schemas have an example value defined.
openApiStyleValidateModelPropertiesDescription	SettingKey[Option[Boolean]]	Ensures that the properties of the Schemas have a description value defined.
openApiStyleValidateModelRequiredProperties	SettingKey[Option[Boolean]]	Ensures that all required properties of the Schemas are listed among their properties.
openApiStyleValidateNaming	SettingKey[Option[Boolean]]	Ensures the names follow a given naming convention.
openApiStyleIgnoreHeaderXNaming	SettingKey[Option[Boolean]]	Exclude from validation header parameters starting with x-.
openApiStylePathNamingConvention	SettingKey[Option[NamingConvention]]	Naming convention for paths.
openApiStyleParameterNamingConvention	SettingKey[Option[NamingConvention]]	Naming convention for parameters.
openApiStyleHeaderNamingConvention	SettingKey[Option[NamingConvention]]	Naming convention for headers.
openApiStylePropertyNamingConvention	SettingKey[Option[NamingConvention]]	Naming convention for properties.

Examples

Please see an sbt-test configuration for examples of using the plugin. Do not run those examples directly, please copy them to separate place first.

Contribution and testing

Write plugin integration tests under src/sbt-test.

Execute next command to run tests:

sbt scripted

More information about how to write and execute tests is here.

Credits

Based heavily on sbt-openapi-generator.