Options for OpenAPI Generator are the same whether you're using the CLI, Maven/Gradle Plugins, or Online generation options.
This page demonstrates navigating the options via CLI. Commands are presented here in a logical progression as a tutorial, but you're welcome to skip directly to the [generate](#generate) command.
## help
The `help` option lists all commands available to the CLI.
```bash
openapi-generator help
usage: openapi-generator-cli <command> [<args>]
The most commonly used openapi-generator-cli commands are:
config-help Config help for chosen lang
generate Generate code with the specified generator.
help Display help information
list Lists the available generators
meta MetaGenerator. Generator for creating a new template set and configuration for Codegen. The output will be based on the language you specify, and includes default templates to include.
validate Validate specification
version Show version information
See 'openapi-generator-cli help <command>' for more information on a specific
command.
```
## list
The `list` command outputs a formatted list of every available generator. Pass the `-s/--short` option if you would like a CSV output for easy parsing.
```bash
openapi-generator help list
NAME
openapi-generator-cli list - Lists the available generators
When format=markdown, include this option to write out markdown
headers (e.g. for docusaurus).
--named-header
Header includes the generator name, for clarity in output
-o <outputlocation>, --output <outputlocation>
Optionally write help to this location, otherwise default is
standard output
```
The option of note is `-g/--generator-name` (other options are exposed for tooling).
You may pass any generator name (see [list](#list) command) to `-g`, and options specific to that generator will be displayed. Some generators have _many_ options, while others may have only a few.
Example:
```bash
openapi-generator config-help -g go
```
Outputs:
```text
CONFIG OPTIONS
packageName
Go package name (convention: lowercase). (Default: openapi)
hideGenerationTimestamp
Hides the generation timestamp when files are generated. (Default: true)
whether to include support for application/xml content type and include XML annotations in the model (works with libraries that provide support for JSON and XML) (Default: false)
prependFormOrBodyParameters
Add form or body parameters to the beginning of the parameter list. (Default: false)
```
To pass these go client generator-specific options to the `generate` command for a go client, use the `--additional-properties` option. See the [generate](#generate) command section for an example.
## meta
The `meta` command creates a new Java class and template files, used for creating your own custom templates.
```bash
openapi-generator help meta
NAME
openapi-generator-cli meta - MetaGenerator. Generator for creating a new
template set and configuration for Codegen. The output will be based on
the language you specify, and includes default templates to include.
SYNOPSIS
openapi-generator-cli meta [(-n <name> | --name <name>)]
where to write the generated files (current dir by default)
-p <package>, --package <package>
the package to put the main class into (defaults to
org.openapitools.codegen)
-t <type>, --type <type>
the type of generator that is created
```
For an in-depth example of using the `meta` command, see [Customization](./customization.md).
## validate
The `validate` command allows you to validate an input specification, optionally providing recommendations for error fixes or other improvements (if available).
location of the OpenAPI spec, as URL or file (required)
--recommend
```
Valid Spec Example (using [petstore-v3.0.yaml](https://raw.githubusercontent.com/OpenAPITools/openapi-generator/master/modules/openapi-generator-gradle-plugin/samples/local-spec/petstore-v3.0.yaml))
```bash
openapi-generator validate -i petstore-v3.0.yaml
```
```text
Validating spec (petstore-v3.0.yaml)
No validation issues detected.
```
Invalid Spec Example (using [petstore-v3.0-invalid.yaml](https://raw.githubusercontent.com/OpenAPITools/openapi-generator/master/modules/openapi-generator-gradle-plugin/samples/local-spec/petstore-v3.0-invalid.yaml)):
An example bash completion script can be found in the repo at [scripts/openapi-generator-cli-completion.bash](https://github.com/OpenAPITools/openapi-generator/blob/master/scripts/openapi-generator-cli-completion.bash).
The `generate` command is the workhorse of the generator toolset. As such, it has _many_ more options and the previous commands. The abbreviated options are below, but you may expand the full descriptions.
The following examples use [petstore.yaml](https://raw.githubusercontent.com/openapitools/openapi-generator/master/modules/openapi-generator/src/test/resources/2_0/petstore.yaml).
#### Additional Properties
Generator-specific options should be passed as `--additional-properties`:
```bash
openapi-generator generate -g go --additional-properties=prependFormOrBodyParameters=true \
-o out -i petstore.yaml
```
To pass more than one generator property, these can be combined via comma:
Most generators allow for types bound to the OpenAPI Specification's types to be remapped to a user's desired types. Not _all_ type mappings can be reassigned, as some generators define mappings which are tightly coupled to the built-in templates.
If you're not using your own templates with star/glob package imports, you will most likely need to combine `--type-mappings` and `--import-mappings` together.
*`--type-mappings` Defines the user's target type
*`--import-mappings` Informs the template of the type to be imported
Here's how one might change the `kotlin-spring` server generator's default of `OffsetDateTime` to `LocalDateTime`:
> NOTE: mappings are applied to `DateTime`, as this is the representation of the primitive type. See [DefaultCodegen](https://github.com/OpenAPITools/openapi-generator/blob/7cee999543fcc00b7c1eb9f70f0456b707c7f9e2/modules/openapi-generator/src/main/java/org/openapitools/codegen/DefaultCodegen.java#L1431).
### Target External Models
Sometimes you don't want the codegen to make a model for you--you might want to just include one that already exists in your codebase. Say you already have a `User` object and want to reuse that, which has a different model package from the other generated files:
First, indicate that the class is already included by default. This will keep the codegen from trying to generate the class.
```bash
--language-specific-primitives=Pet
```
This command line option will tell the generator to consider `Pet` a "primitive" type.
Next, if the `Pet` class is a different package, add an `--import-mapping` to tell the generator to include that import wherever `Pet` is used:
```bash
--import-mappings=Pet=com.yourpackage.models.Pet
```
Now the codegen will know what to import from that specific package.
NOTE: `import-mappings` is assigned a key-value pair in this example, but multiple values can be comma-separate. For instance:
