# 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 = [        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-schemaCONFIG 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

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 = "mysql-schema"    inputSpec = "$rootDir/spec.yaml".toString()    outputDir = "$buildDir/mysql".toString()    configOptions = [            identifierNamingConvention: "snake_case"    ]}

Edit this page
Last updated on 3/12/2021 by William Cheng

- Tool-specific Declarations
- Discovering Options