sbt-openapi-generator

Scala CI

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