sbt-openapi-generator

A Sbt plugin to support the OpenAPI generator project.

Usage

Add to your project/plugins.sbt:

addSbtPlugin("org.openapitools" % "sbt-openapi-generator" % "5.3.0")

Configuration

Configuration based on project module is recommended way to separate specifications by modules.

You must define one of the settings openApiInputSpec or openApiConfigFile to able run plugin to generate.

Settings will be picked up from openApiConfigFile first if defined and then will be overwritten with module specified settings if provided

With the next example module generated will be defined as:

lazy val generated = project.in(file("generated"))
  .settings(
    openApiInputSpec := "openapi.yaml",
    openApiConfigFile := "config.yaml"
  )

There is a helpers to have boolean settings more readable. Instead of Some(true) it possible to do next:

    openApiValidateSpec := SettingDisabled,
    openApiGenerateModelTests := SettingEnabled,

Execution

To print all available languages use

sbt openApiGenerators

To run template generation process

sbt openApiGenerate

or per defined module

sbt generated/openApiGenerate

Settings

Setting	Type	Description
openApiGeneratorName *	String	The name of the generator which will handle codegen. (see "openApiGenerators" task) Required. Can be provided as generatorName option of openApiConfigFile json config
openApiInputSpec *	String	The Open API 2.0/3.x specification location (file or url) Required. Can be provided as inputSpec option of openApiConfigFile json config
openApiOutputDir	String	The output target directory into which code will be generated
openApiConfigFile **	String	Path to json configuration file This setting is required with generatorName and inputSpec settings provided if sbt settings openApiGeneratorName and openApiInputSpec are absent
openApiAdditionalProperties	Map[String, String]	Sets additional properties that can be referenced by the mustache templates in the format of name=value,name=value. You can also have multiple occurrences of this option
openApiGlobalProperties	Map[String, String]	Sets specified system properties
openApiVerbose	Option[Boolean]	The verbosity of generation
openApiValidateSpec	Option[Boolean]	Whether or not an input specification should be validated upon generation
openApiTemplateDir	String	The template directory holding a custom template
openApiAuth	String	Adds authorization headers when fetching the OpenAPI definitions remotely. Pass in a URL-encoded string of name:header with a comma separating multiple values
openApiSkipOverwrite	Option[Boolean]	Specifies if the existing files should be overwritten during the generation
openApiPackageName	String	Package for generated classes (where supported)
openApiApiPackage	String	Package for generated api classes
openApiModelPackage	String	Package for generated models
openApiModelNamePrefix	String	Prefix that will be prepended to all model names
openApiModelNameSuffix	String	Suffix that will be appended to all model names
openApiInstantiationTypes	Map[String, String]	Sets instantiation type mappings
openApiTypeMappings	Map[String, String]	Sets mappings between OpenAPI spec types and generated code types
openApiServerVariables	Map[String, String]	Sets server variable for server URL template substitution, in the format of name=value,name=value. You can also have multiple occurrences of this option
openApiLanguageSpecificPrimitives	List[String]	Specifies additional language specific primitive types in the format of type1,type2,type3,type3. For example: String,boolean,Boolean,Double
openApiImportMappings	Map[String, String]	Specifies mappings between a given class and the import that should be used for that class
openApiInvokerPackage	String	Root package for generated code
openApiGroupId	String	groupId in generated pom.xml/build.sbt
openApiId	String	artifactId in generated pom.xml/build.sbt. This also becomes part of the generated library's filename
openApiLibrary	String	library template (sub-template)
openApiGitHost	String	Git host, e.g. gitlab.com
openApiGitUserId	String	Git user ID, e.g. openapitools
openApiGitRepoId	String	Git repo ID, e.g. openapi-generator
openApiReleaseNote	String	Release note, default to 'Minor update'
openApiHttpUserAgent	String	HTTP user agent, e.g. codegen_csharp_api_client, default to 'OpenAPI-Generator/{packageVersion}}/{language}'
openApiReservedWordsMappings	Map[String, String]	]("Specifies how a reserved name should be escaped to
openApiIgnoreFileOverride	String	Specifies an override location for the .openapi-generator-ignore file. Most useful on initial generation.
openApiRemoveOperationIdPrefix	Option[Boolean]	Remove prefix of operationId, e.g. config_getId => getId
openApiApiFilesConstrainedTo	List[String]	Defines which API-related files should be generated. This allows you to create a subset of generated files (or none at all)
openApiModelFilesConstrainedTo	List[String]	Defines which model-related files should be generated. This allows you to create a subset of generated files (or none at all)
openApiSupportingFilesConstrainedTo	List[String]	Defines which supporting files should be generated. This allows you to create a subset of generated files (or none at all
openApiGenerateModelTests	Option[Boolean]	Specifies that model tests are to be generated
openApiGenerateModelDocumentation	Option[Boolean]	Defines whether or not model-related documentation files should be generated
openApiGenerateApiTests	Option[Boolean]	Specifies that api tests are to be generated
openApiGenerateApiDocumentation	Option[Boolean]	Defines whether or not api-related documentation files should be generated
openApiWithXml	Option[Boolean]	A special-case setting which configures some generators with XML support. In some cases, this forces json OR xml, so the default here is false
openApiLogToStderr	Option[Boolean]	To write all log messages (not just errors) to STDOUT
openApiEnablePostProcessFile	Option[Boolean]	Enable post-processing file using environment variables
openApiSkipValidateSpec	Option[Boolean]	To skip spec validation. When true, we will skip the default behavior of validating a spec before generation
openApiGenerateAliasAsModel	Option[Boolean]	Generate model implementation for aliases to map and array schemas
openApiGenerateMetadata	Option[Boolean]	Generate metadata files used by OpenAPI Generator. This includes .openapi-generator-ignore and any files within .openapi-generator.

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 Tests

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