Configuration Options

Our tooling supports the following types of configuration:

• global properties
  • properties with cross-cutting concerns which control generation, but don't belong to individual generators
  • Example: debugSupportingFiles prints the contents of template data bound to supporting files
• config options
  • configuration specific to each individual generator
  • these options are susceptible to validation within the defining generator; a config option of the same name across multiple generators may be validated differently in each
  • NOTE: The CLI accepts config options as "additional properties"
• additional properties
  • these are the properties which will be passed to templates
  • generally used to pass user-defined properties to custom templates
  • many config options may also be passed as additional properties, however generators will read/modify/rewrite config options
  • users may pass custom additional properties and use these within templates (e.g. a custom generatedBy key with a value of Jim Schubert for inclusion in a custom CVS-like header)
• top-level properties specific to individual tools/plugins used to bootstrap our tooling

Tool-specific Declarations

The READMEs for the CLI, Gradle Plugin, Maven Plugin, and SBT Plugin may have top-level or tooling specific options which appear to duplicate 'config options' or 'global properties'. Each may also expose user-facing properties slightly differently from the other tools. This may occur due to:

• Conventions used by the underlying tooling
• Limitations in underlying frameworks which define how properties must be declared
• Continuation of support for "legacy" invocation patterns
• Mistakes in documentation and/or contributions (please do file a bug)

Take, for example, the CLI option of --skip-validate-spec. This flag sets the value to true with no option to set it to false (the default internally). The maven and gradle plugins allow for the top-level option skipValidateSpec to have a value of true or false. The SBT plugin, on the other hand, follows community convention and this property is openApiSkipValidateSpec.

How you provide values to options also depends on the tool. OpenAPI Generator supports global properties for selective generation -- such as apis -- to have either a blank value or a comma-separated list of selected values. We would define this in CLI as --global-property apis or --global-property apis=Equipment. In the Gradle Plugin, these properties are set directly as strings:

openApiGenerate {
    globalProperties.set([
        apis: "",
        models: "User:Pet"
    ])
}

In the Maven plugin, we're limited by XML syntax where <apis/> and <apis></apis> are treated the same as if the apis node was undefined; there's no way to provide an empty string as a default. Instead, we have to extract the global property into its own properties which maintain the two states supported elsewhere (i.e. "all apis" or "select apis"). We have generateApis which accepts a boolean and apisToGenerate which accepts a comma-separated selection list.

Discovering Options

Refer to global properties for a list of available global properties and their usage.

Top-level tooling options are defined in CLI usage. Many of these options directly map to camel case options in other tools, but do refer to plugin documentation for full details or plugin-specific differences.

Config options for generators are available in documentation online. You may also use the CLI to query config options for a target generator using openapi-generator config-help -g <generator-name>. For example:

$ openapi-generator config-help -g mysql-schema

CONFIG OPTIONS

    defaultDatabaseName
        Default database name for all MySQL queries (Default: )

    identifierNamingConvention
        Naming convention of MySQL identifiers(table names and column names). This is not related to database name which is defined by defaultDatabaseName option (Default: original)
            original - Do not transform original names
            snake_case - Use snake_case names

    jsonDataTypeEnabled
        Use special JSON MySQL data type for complex model properties. Requires MySQL version 5.7.8. Generates TEXT data type when disabled (Default: true)

    namedParametersEnabled
        Generates model prepared SQLs with named parameters, eg. :petName. Question mark placeholder used when option disabled. (Default: false)

This output provides the name of the configuration option. A set of acceptable values for any constrained values will print as an indented list (e.g. identifierNamingConvention above).

Suppose you want to apply snake case naming to mysql schema outputs. Your configuration might resemble the following examples.

CLI

openapi-generator -g mysql-schema -o out -i spec.yaml --additional-properties=identifierNamingConvention=snake_case,useSingleRequestParameter=true,withInterfaces=true

It may seem like a typo but there are two = signs in the above example.

Maven Plugin

<execution>
    <id>mysql-schema</id>
    <phase>generate-sources</phase>
    <goals>
        <goal>generate</goal>
    </goals>
    <configuration>
        <inputSpec>spec.yaml</inputSpec>
        <generatorName>mysql-schema</generatorName>
        <configOptions>
            <identifierNamingConvention>snake_case</identifierNamingConvention>
        </configOptions>
        <output>${project.build.directory}/generated-sources/mysql</output>
    </configuration>
</execution>

Gradle Plugin

openApiGenerate {
    generatorName.set("mysql-schema")
    inputSpec.set("$rootDir/spec.yaml")
    outputDir.set("$buildDir/mysql")
    configOptions.set([
            identifierNamingConvention: "snake_case"
    ])
}