Skip to content
Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?
Go to file
Latest commit 31a89e3 Feb 1, 2023 History
* update to 6.4.0 snapshot

* update samples

* update doc
15 contributors

Users who have contributed to this file

@wing328 @jimschubert @jmini @mmiikkkkaa @karismann @ackintosh @tomplus @borsch @MartinDelille @MartinHatas @kariem @InfoSec812


A Maven plugin to support the OpenAPI generator project


Add to your build->plugins section (default phase is generate-sources phase)

    <!-- RELEASE_VERSION -->
    <!-- /RELEASE_VERSION -->

Followed by:

mvn clean compile

General Configuration parameters

💡 These general configurations should be in the same level

Option Property Description
verbose openapi.generator.maven.plugin.verbose verbose mode (false by default)
inputSpec openapi.generator.maven.plugin.inputSpec OpenAPI Spec file path
language openapi.generator.maven.plugin.language target generation language (deprecated, replaced by generatorName as values here don't represent only 'language' any longer)
generatorName openapi.generator.maven.plugin.generatorName target generator name
output openapi.generator.maven.plugin.output target output path (default is ${}/generated-sources/openapi. Can also be set globally through the openapi.generator.maven.plugin.output property)
gitHost openapi.generator.maven.plugin.gitHost The git host, e.g.
gitUserId openapi.generator.maven.plugin.gitUserId sets git information of the project
gitRepoId openapi.generator.maven.plugin.gitRepoId sets the repo ID (e.g. openapi-generator)
templateDirectory openapi.generator.maven.plugin.templateDirectory directory with mustache templates
templateResourcePath openapi.generator.maven.plugin.templateResourcePath directory with mustache templates via resource path. This option will overwrite any option defined in templateDirectory.
engine openapi.generator.maven.plugin.engine The name of templating engine to use, "mustache" (default) or "handlebars" (beta)
auth openapi.generator.maven.plugin.auth adds authorization headers when fetching the OpenAPI definitions remotely. Pass in a URL-encoded string of name:header with a comma separating multiple values
configurationFile openapi.generator.maven.plugin.configurationFile Path to separate json configuration file. File content should be in a json format {"optionKey":"optionValue", "optionKey1":"optionValue1"...} Supported options can be different for each generator. Run config-help -g {generator name} command for generator-specific config options
skipOverwrite openapi.generator.maven.plugin.skipOverwrite Specifies if the existing files should be overwritten during the generation. (false by default)
apiPackage openapi.generator.maven.plugin.apiPackage the package to use for generated api objects/classes
modelPackage openapi.generator.maven.plugin.modelPackage the package to use for generated model objects/classes
invokerPackage openapi.generator.maven.plugin.invokerPackage the package to use for the generated invoker objects
packageName openapi.generator.maven.plugin.packageName the default package name to use for the generated objects
groupId openapi.generator.maven.plugin.groupId sets project information in generated pom.xml/build.gradle or other build script. Language-specific conversions occur in non-jvm generators
artifactId openapi.generator.maven.plugin.artifactId sets project information in generated pom.xml/build.gradle or other build script. Language-specific conversions occur in non-jvm generators
artifactVersion openapi.generator.maven.plugin.artifactVersion sets project information in generated pom.xml/build.gradle or other build script. Language-specific conversions occur in non-jvm generators
library openapi.generator.maven.plugin.library library template (sub-template)
modelNamePrefix openapi.generator.maven.plugin.modelNamePrefix Sets the prefix for model classes and enums
modelNameSuffix openapi.generator.maven.plugin.modelNameSuffix Sets the suffix for model classes and enums
apiNameSuffix openapi.generator.maven.plugin.apiNameSuffix Sets the suffix for api classes
ignoreFileOverride openapi.generator.maven.plugin.ignoreFileOverride specifies the full path to a .openapi-generator-ignore used for pattern based overrides of generated outputs
httpUserAgent openapi.generator.maven.plugin.httpUserAgent Sets custom User-Agent header value
removeOperationIdPrefix openapi.generator.maven.plugin.removeOperationIdPrefix remove operationId prefix (e.g. user_getName => getName)
skipOperationExample openapi.generator.maven.plugin.skipOperationExample skip examples defined in the operation
logToStderr openapi.generator.maven.plugin.logToStderr write all log messages (not just errors) to STDERR
enablePostProcessFile openapi.generator.maven.plugin. enable file post-processing hook
skipValidateSpec openapi.generator.maven.plugin.skipValidateSpec Whether or not to skip validating the input spec prior to generation. By default, invalid specifications will result in an error.
strictSpec openapi.generator.maven.plugin.strictSpec Whether or not to treat an input document strictly against the spec. 'MUST' and 'SHALL' wording in OpenAPI spec is strictly adhered to. e.g. when false, no fixes will be applied to documents which pass validation but don't follow the spec.
generateAliasAsModel openapi.generator.maven.plugin.generateAliasAsModel generate alias (array, map) as model
configOptions N/A a map of generator-specific parameters. To show a full list of generator-specified parameters (options), please use configHelp (explained below)
instantiationTypes openapi.generator.maven.plugin.instantiationTypes sets instantiation type mappings in the format of type=instantiatedType,type=instantiatedType. For example (in Java): array=ArrayList,map=HashMap. In other words array types will get instantiated as ArrayList in generated code. You can also have multiple occurrences of this option
importMappings openapi.generator.maven.plugin.importMappings specifies mappings between a given class and the import that should be used for that class in the format of type=import,type=import. You can also have multiple occurrences of this option
typeMappings openapi.generator.maven.plugin.typeMappings sets mappings between OpenAPI spec types and generated code types in the format of OpenAPIType=generatedType,OpenAPIType=generatedType. For example: array=List,map=Map,string=String. You can also have multiple occurrences of this option. To map a specified format, use type+format, e.g. string+password=EncryptedString will map type: string, format: password to EncryptedString.
languageSpecificPrimitives openapi.generator.maven.plugin.languageSpecificPrimitives specifies additional language specific primitive types in the format of type1,type2,type3,type3. For example: String,boolean,Boolean,Double. You can also have multiple occurrences of this option
additionalProperties openapi.generator.maven.plugin.additionalProperties 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
serverVariableOverrides openapi.generator.maven.plugin.serverVariableOverrides A map of server variable overrides for specs that support server URL templating
reservedWordsMappings openapi.generator.maven.plugin.reservedWordsMappings specifies how a reserved name should be escaped to. Otherwise, the default _<name> is used. For example id=identifier. You can also have multiple occurrences of this option
generateApis openapi.generator.maven.plugin.generateApis generate the apis (true by default). Specific apis may be defined as a CSV via apisToGenerate.
apisToGenerate openapi.generator.maven.plugin.apisToGenerate A comma separated list of apis to generate. All apis is the default.
generateModels openapi.generator.maven.plugin.generateModels generate the models (true by default). Specific models may be defined as a CSV via modelsToGenerate.
modelsToGenerate openapi.generator.maven.plugin.modelsToGenerate A comma separated list of models to generate. All models is the default.
generateSupportingFiles openapi.generator.maven.plugin.generateSupportingFiles generate the supporting files (true by default)
supportingFilesToGenerate openapi.generator.maven.plugin.supportingFilesToGenerate A comma separated list of supporting files to generate. All files is the default.
generateModelTests openapi.generator.maven.plugin.generateModelTests generate the model tests (true by default. Only available if generateModels is true)
generateModelDocumentation openapi.generator.maven.plugin.generateModelDocumentation generate the model documentation (true by default. Only available if generateModels is true)
generateApiTests openapi.generator.maven.plugin.generateApiTests generate the api tests (true by default. Only available if generateApis is true)
generateApiDocumentation openapi.generator.maven.plugin.generateApiDocumentation generate the api documentation (true by default. Only available if generateApis is true)
withXml openapi.generator.maven.plugin.withXml enable XML annotations inside the generated models and API (only works with Java language and libraries that provide support for JSON and XML)
skip codegen.skip skip code generation (false by default. Can also be set globally through the codegen.skip property)
skipIfSpecIsUnchanged codegen.skipIfSpecIsUnchanged Skip the execution if the source file is older than the output folder (false by default. Can also be set globally through the codegen.skipIfSpecIsUnchanged property)
addCompileSourceRoot openapi.generator.maven.plugin.addCompileSourceRoot Add the output directory to the project as a source root, so that the generated java types are compiled and included in the project artifact (true by default). Mutually exclusive with addTestCompileSourceRoot.
addTestCompileSourceRoot openapi.generator.maven.plugin.addTestCompileSourceRoot Add the output directory to the project as a test source root, so that the generated java types are compiled only for the test classpath of the project (false by default). Mutually exclusive with addCompileSourceRoot.
environmentVariables N/A deprecated. Use globalProperties instead.
globalProperties N/A A map of items conceptually similar to "environment variables" or "system properties". These are available to all aspects of the generation flow. See Global Properties for list of available properties.
configHelp codegen.configHelp dumps the configuration help for the specified library (generates no sources)

Configuring map structures

For configuration options documented as a map above, the key/value options may be configured as free-form nodes under these options. This takes the format:


This configuration node location will match that of the plugin configuration examples at the top of this document and in the section below. Here, option matches in option name in the first column in the table from the previous section. The key and value text are any values you'd like to provide for that option. As an example, to configure globalProperties to match the --global-property models=User:Pet example from our Selective Generation documentation, see below.


Notice that some of these environment variable options may overwrite or conflict with other options available to the maven plugin. For example, the above globalProperties example is equivalent to the following:


The difference here is that you may define generateModels and modelsToGenerate as properties, while globalProperties may only be configured as a configuration node.

Type and import mappings

To override the mappings between OpenAPI spec types and the types used in the generated code, set typeMappings.

        <!-- convert Double to BigDecimal -->

For types that are not already included in the generator configuration, you may need to add a corresponding importMapping too.

    <!-- convert file/binary to JAX-RS StreamingOutput -->

Custom Generator

Specifying a custom generator is a bit different. It doesn't support the classpath:/ syntax, but it does support the fully qualified name of the package. You can also specify your custom templates, which also get pulled in. Notice the dependency on a project, in the plugin scope. That would be your generator/template jar.

                <!-- language file, like e.g. JavaJaxRSCodegen -->



Sample configuration

Please see an example configuration for using the plugin. To run these examples, explicitly pass the file to maven. Example:

mvn -f non-java.xml compile