2019-01-18 04:39:33 -05:00
---
id: usage
title: Usage
---
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.
2021-04-03 05:28:25 +02:00
``` text
2021-03-09 20:14:57 +13:00
openapi-generator-cli help
2019-01-18 04:39:33 -05:00
usage: openapi-generator-cli <command> [<args>]
The most commonly used openapi-generator-cli commands are:
2020-05-28 00:12:59 -04:00
author Utilities for authoring generators or customizing templates.
2021-04-03 05:28:25 +02:00
batch Generate code in batch via external configs.
2019-01-18 04:39:33 -05:00
config-help Config help for chosen lang
generate Generate code with the specified generator.
2020-05-28 00:12:59 -04:00
help Display help information about openapi-generator
2019-01-18 04:39:33 -05:00
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
2020-05-28 00:12:59 -04:00
version Show version information used in tooling
2019-01-18 04:39:33 -05:00
See 'openapi-generator-cli help <command>' for more information on a specific
command.
2020-04-01 23:05:25 -04:00
```
## version
2021-04-03 14:46:22 +08:00
The version command provides version information, returning either the version by default, the git commit sha when passed `--sha` , or verbose output when passed `--full` .
2020-04-01 23:05:25 -04:00
2021-04-03 05:28:25 +02:00
``` text
2020-04-01 23:05:25 -04:00
NAME
2021-04-03 05:28:25 +02:00
openapi-generator-cli version - Show version information used in tooling
2020-04-01 23:05:25 -04:00
SYNOPSIS
2021-04-03 05:28:25 +02:00
openapi-generator-cli version [--full] [--sha]
2020-04-01 23:05:25 -04:00
OPTIONS
2021-04-03 05:28:25 +02:00
--full
Full version details
2020-04-01 23:05:25 -04:00
--sha
Git commit SHA version
2019-01-18 04:39:33 -05:00
```
## 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.
2021-04-03 05:28:25 +02:00
``` text
2021-03-09 20:14:57 +13:00
openapi-generator-cli help list
2019-01-18 04:39:33 -05:00
NAME
openapi-generator-cli list - Lists the available generators
SYNOPSIS
2019-08-12 08:25:52 -04:00
openapi-generator-cli list [(-i <include> | --include <include>)]
[(-s | --short)]
2019-01-18 04:39:33 -05:00
OPTIONS
2019-08-12 08:25:52 -04:00
-i <include>, --include <include>
comma-separated list of stability indexes to include (value:
all,beta,stable,experimental,deprecated). Excludes deprecated by
default.
2019-01-18 04:39:33 -05:00
-s, --short
shortened output (suitable for scripting)
```
Example:
``` bash
2021-03-09 20:14:57 +13:00
openapi-generator-cli list -s | tr ',' '\n'
2019-01-18 04:39:33 -05:00
```
For the full list of generators, refer to the [Generators List ](./generators.md ).
## config-help
The `config-help` option provides details about
2021-04-03 05:28:25 +02:00
``` text
2021-03-09 20:14:57 +13:00
openapi-generator-cli help config-help
2019-01-18 04:39:33 -05:00
NAME
openapi-generator-cli config-help - Config help for chosen lang
SYNOPSIS
openapi-generator-cli config-help
2021-04-03 05:28:25 +02:00
[(-f <output format> | --format <output format>)] [--feature-set]
[--full-details]
2019-01-18 04:39:33 -05:00
[(-g <generator name> | --generator-name <generator name>)]
2021-04-03 05:28:25 +02:00
[--import-mappings] [--instantiation-types]
[--language-specific-primitive] [--markdown-header] [--named-header]
[(-o <output location> | --output <output location>)] [--reserved-words]
2019-01-18 04:39:33 -05:00
OPTIONS
-f <output format>, --format <output format>
2019-03-26 09:22:59 +02:00
Write output files in the desired format. Options are 'text',
'markdown' or 'yamlsample'. Default is 'text'.
2019-01-18 04:39:33 -05:00
2021-04-03 05:28:25 +02:00
--feature-set
displays feature set as supported by the generator
--full-details
displays CLI options as well as other configs/mappings (implies
--instantiation-types, --reserved-words,
--language-specific-primitives, --import-mappings,
--supporting-files)
2019-01-18 04:39:33 -05:00
-g <generator name>, --generator-name <generator name>
generator to get config help for
2021-04-03 05:28:25 +02:00
--import-mappings
displays the default import mappings (types and aliases, and what
imports they will pull into the template)
--instantiation-types
displays types used to instantiate simple type/alias names
--language-specific-primitive
displays the language specific primitives (types which require no
additional imports, or which may conflict with user defined model
names)
2019-01-18 04:39:33 -05:00
--markdown-header
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 <output location>, --output <output location>
Optionally write help to this location, otherwise default is
standard output
2021-04-03 05:28:25 +02:00
--reserved-words
displays the reserved words which may result in renamed model or
property names
2019-01-18 04:39:33 -05:00
```
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
2021-03-09 20:14:57 +13:00
openapi-generator-cli config-help -g go
2019-01-18 04:39:33 -05:00
```
Outputs:
``` text
CONFIG OPTIONS
packageName
Go package name (convention: lowercase). (Default: openapi)
hideGenerationTimestamp
Hides the generation timestamp when files are generated. (Default: true)
packageVersion
Go package version. (Default: 1.0.0)
withGoCodegenComment
2020-02-13 08:04:05 +01:00
whether to include Go codegen comment to disable Go Lint and collapse by default in GitHub PRs and diffs (Default: false)
2019-01-18 04:39:33 -05:00
withXml
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.
2021-04-03 05:28:25 +02:00
``` text
2021-03-09 20:14:57 +13:00
openapi-generator-cli help meta
2019-01-18 04:39:33 -05:00
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
2021-04-03 05:28:25 +02:00
openapi-generator-cli meta [(-l <language> | --language <language>)]
[(-n <name> | --name <name>)]
2019-01-18 04:39:33 -05:00
[(-o <output directory> | --output <output directory>)]
[(-p <package> | --package <package>)] [(-t <type> | --type <type>)]
OPTIONS
2021-04-03 05:28:25 +02:00
-l <language>, --language <language>
the implementation language for the generator class
2019-01-18 04:39:33 -05:00
-n <name>, --name <name>
the human-readable name of the generator
-o <output directory>, --output <output directory>
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).
2021-04-03 05:28:25 +02:00
``` text
2021-03-09 20:14:57 +13:00
openapi-generator-cli help validate
2019-01-18 04:39:33 -05:00
NAME
openapi-generator-cli validate - Validate specification
SYNOPSIS
openapi-generator-cli validate
(-i <spec file> | --input-spec <spec file>) [--recommend]
OPTIONS
-i <spec file>, --input-spec <spec file>
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
2021-03-09 20:14:57 +13:00
openapi-generator-cli validate -i petstore-v3.0.yaml
2019-01-18 04:39:33 -05:00
```
``` 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 )):
``` bash
2021-03-09 20:14:57 +13:00
openapi-generator-cli validate -i petstore-v3.0-invalid.yaml
2019-01-18 04:39:33 -05:00
```
``` text
Validating spec (petstore-v3.0-invalid.yaml)
Errors:
-attribute info is missing
[error] Spec has 1 errors.
```
## completion
Although not documented in the `help` output, the CLI offers a `completion` command, which can be used for auto-completion.
This command takes one or more parameters representing the args list you would otherwise pass to `openapi-generator` . For example:
``` bash
2021-03-09 20:14:57 +13:00
openapi-generator-cli completion config-help
2019-01-18 04:39:33 -05:00
-o
--output
2019-08-12 08:25:52 -04:00
--named-header
2019-01-18 04:39:33 -05:00
-g
--generator-name
2019-08-12 08:25:52 -04:00
-f
--format
--markdown-header
2019-01-18 04:39:33 -05:00
```
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 ).
## generate
2020-02-26 01:25:00 -05:00
The `generate` command is the workhorse of the generator toolset. As such, it has _ many _ more options available than the previous commands. The abbreviated options are below, but you may expand the full descriptions.
2019-01-18 04:39:33 -05:00
2021-04-03 05:28:25 +02:00
``` text
2021-03-09 20:14:57 +13:00
openapi-generator-cli help generate
2019-01-18 04:39:33 -05:00
NAME
openapi-generator-cli generate - Generate code with the specified
generator.
SYNOPSIS
openapi-generator-cli generate
[(-a <authorization> | --auth <authorization>)]
2020-02-18 20:36:17 -05:00
[--api-name-suffix <api name suffix>] [--api-package <api package>]
[--artifact-id <artifact id>] [--artifact-version <artifact version>]
2020-05-31 07:14:31 -04:00
[(-c <configuration file> | --config <configuration file>)] [--dry-run]
2019-05-03 10:57:47 -04:00
[(-e <templating engine> | --engine <templating engine>)]
[--enable-post-process-file]
2019-01-18 04:39:33 -05:00
[(-g <generator name> | --generator-name <generator name>)]
2020-02-18 20:36:17 -05:00
[--generate-alias-as-model] [--git-host <git host>]
[--git-repo-id <git repo id>] [--git-user-id <git user id>]
2020-05-31 07:14:31 -04:00
[--global-property <global properties>...] [--group-id <group id>]
[--http-user-agent <http user agent>]
2021-04-03 05:28:25 +02:00
[(-i <spec file> | --input-spec <spec file>)]
2019-01-18 04:39:33 -05:00
[--ignore-file-override <ignore file override location>]
[--import-mappings <import mappings>...]
[--instantiation-types <instantiation types>...]
[--invoker-package <invoker package>]
[--language-specific-primitives <language specific primitives>...]
2021-04-03 05:28:25 +02:00
[--legacy-discriminator-behavior] [--library <library>]
[--log-to-stderr] [--minimal-update]
2019-01-18 04:39:33 -05:00
[--model-name-prefix <model name prefix>]
[--model-name-suffix <model name suffix>]
[--model-package <model package>]
2021-04-03 05:28:25 +02:00
[(-o <output directory> | --output <output directory>)] [(-p <additional properties> | --additional-properties <additional properties>)...]
2019-04-30 12:46:48 -04:00
[--package-name <package name>] [--release-note <release note>]
[--remove-operation-id-prefix]
2019-01-18 04:39:33 -05:00
[--reserved-words-mappings <reserved word mappings>...]
2019-08-11 09:57:36 -04:00
[(-s | --skip-overwrite)] [--server-variables <server variables>...]
2021-04-03 05:28:25 +02:00
[--skip-operation-example] [--skip-validate-spec]
[--strict-spec <true/false strict behavior>]
2019-01-18 04:39:33 -05:00
[(-t <template directory> | --template-dir <template directory>)]
[--type-mappings <type mappings>...] [(-v | --verbose)]
```
<details>
2020-02-11 08:22:58 -05:00
<summary>generate OPTIONS</summary>
2021-04-03 05:28:25 +02:00
``` text
2019-01-18 04:39:33 -05:00
OPTIONS
-a <authorization>, --auth <authorization>
adds authorization headers when fetching the OpenAPI definitions
remotely. Pass in a URL-encoded string of name:header with a comma
separating multiple values
2020-02-18 20:36:17 -05:00
--api-name-suffix <api name suffix>
Suffix that will be appended to all API names ('tags'). Default:
Api. e.g. Pet => PetApi. Note: Only ruby, python, jaxrs generators
2021-04-03 05:28:25 +02:00
support this feature at the moment.
2020-02-18 20:36:17 -05:00
2019-01-18 04:39:33 -05:00
--api-package <api package>
package for generated api classes
--artifact-id <artifact id>
2019-08-11 09:57:36 -04:00
artifactId in generated pom.xml. This also becomes part of the
generated library's filename
2019-01-18 04:39:33 -05:00
--artifact-version <artifact version>
2019-08-11 09:57:36 -04:00
artifact version in generated pom.xml. This also becomes part of the
generated library's filename
2019-01-18 04:39:33 -05:00
-c <configuration file>, --config <configuration file>
2020-02-18 20:36:17 -05:00
Path to configuration file. It can be JSON or YAML. If file is JSON,
the content should have the format {"optionKey":"optionValue",
"optionKey1":"optionValue1"...}. If file is YAML, the content should
have the format optionKey: optionValue. Supported options can be
different for each language. Run config-help -g {generator name}
command for language-specific config options.
2019-01-18 04:39:33 -05:00
2020-02-18 20:36:17 -05:00
--dry-run
Try things out and report on potential changes (without actually
making changes).
2019-05-03 10:57:47 -04:00
-e <templating engine>, --engine <templating engine>
templating engine: "mustache" (default) or "handlebars" (beta)
2019-01-18 04:39:33 -05:00
--enable-post-process-file
2020-02-18 20:36:17 -05:00
Enable post-processing file using environment variables.
2019-01-18 04:39:33 -05:00
-g <generator name>, --generator-name <generator name>
2019-05-03 10:57:47 -04:00
generator to use (see list command for list)
--generate-alias-as-model
2020-02-16 17:23:00 -08:00
Generate model implementation for aliases to map and array schemas.
2020-05-31 07:14:31 -04:00
An 'alias' is an array, map, or list which is defined inline in a
OpenAPI document and becomes a model in the generated code. A 'map'
schema is an object that can have undeclared properties, i.e. the
'additionalproperties' attribute is set on that object. An 'array'
schema is a list of sub schemas in a OAS document
2019-01-18 04:39:33 -05:00
2020-02-18 20:36:17 -05:00
--git-host <git host>
Git host, e.g. gitlab.com.
2019-01-18 04:39:33 -05:00
--git-repo-id <git repo id>
Git repo ID, e.g. openapi-generator.
--git-user-id <git user id>
Git user ID, e.g. openapitools.
2020-05-31 07:14:31 -04:00
--global-property <global properties>
sets specified global properties (previously called 'system
properties') in the format of name=value,name=value (or multiple
options, each with name=value)
2019-01-18 04:39:33 -05:00
--group-id <group id>
groupId in generated pom.xml
--http-user-agent <http user agent>
HTTP user agent, e.g. codegen_csharp_api_client, default to
2020-05-11 07:30:20 +01:00
'OpenAPI-Generator/{packageVersion}/{language}'
2019-01-18 04:39:33 -05:00
-i <spec file>, --input-spec <spec file>
2021-04-03 05:28:25 +02:00
location of the OpenAPI spec, as URL or file (required if not loaded
via config using -c)
2019-01-18 04:39:33 -05:00
--ignore-file-override <ignore file override location>
Specifies an override location for the .openapi-generator-ignore
file. Most useful on initial generation.
--import-mappings <import mappings>
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.
--instantiation-types <instantiation types>
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.
--invoker-package <invoker package>
root package for generated code
--language-specific-primitives <language specific primitives>
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.
2021-04-03 05:28:25 +02:00
--legacy-discriminator-behavior
Set to false for generators with better support for discriminators.
(Python, Java, Go, PowerShell, C#have this enabled by default).
2019-01-18 04:39:33 -05:00
--library <library>
library template (sub-template)
--log-to-stderr
write all log messages (not just errors) to STDOUT. Useful for
2021-04-03 05:28:25 +02:00
piping the JSON output of debug options (e.g. `--global-property
debugOperations`) to an external parser directly while testing a
generator.
2019-01-18 04:39:33 -05:00
2019-05-03 10:57:47 -04:00
--minimal-update
Only write output files that have changed.
2019-01-18 04:39:33 -05:00
--model-name-prefix <model name prefix>
2020-02-18 20:36:17 -05:00
Prefix that will be prepended to all model names.
2019-01-18 04:39:33 -05:00
--model-name-suffix <model name suffix>
2020-02-18 20:36:17 -05:00
Suffix that will be appended to all model names.
2019-01-18 04:39:33 -05:00
--model-package <model package>
package for generated models
-o <output directory>, --output <output directory>
where to write the generated files (current dir by default)
2019-08-11 09:57:36 -04:00
-p <additional properties>, --additional-properties <additional
properties>
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.
2019-05-03 10:57:47 -04:00
--package-name <package name>
package for generated classes (where supported)
2019-01-18 04:39:33 -05:00
--release-note <release note>
Release note, default to 'Minor update'.
--remove-operation-id-prefix
Remove prefix of operationId, e.g. config_getId => getId
--reserved-words-mappings <reserved word mappings>
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.
-s, --skip-overwrite
specifies if the existing files should be overwritten during the
generation.
2019-08-11 09:57:36 -04:00
--server-variables <server variables>
2020-02-18 20:36:17 -05:00
sets server variables overrides for spec documents which support
variable templating of servers.
2019-08-11 09:57:36 -04:00
2021-04-03 05:28:25 +02:00
--skip-operation-example
Skip examples defined in operations to avoid out of memory errors.
2019-01-18 04:39:33 -05:00
--skip-validate-spec
Skips the default behavior of validating an input specification.
2019-05-03 10:57:47 -04:00
--strict-spec <true/false strict behavior>
'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.
2019-01-18 04:39:33 -05:00
-t <template directory>, --template-dir <template directory>
folder containing the template files
--type-mappings <type mappings>
sets mappings between OpenAPI spec types and generated code types in
2019-05-03 10:57:47 -04:00
the format of OpenAPIType=generatedType,OpenAPIType=generatedType.
2019-01-18 04:39:33 -05:00
For example: array=List,map=Map,string=String. You can also have
multiple occurrences of this option.
-v, --verbose
verbose mode
```
</details>
At a minimum, `generate` requires:
* `-g` to specify the generator
* `-o` to specify a meaningful output directory (defaults to the current directory!)
* `-i` to specify the input OpenAPI document
2020-02-03 03:08:51 -05:00
> **NOTE** You may also pass `-Dcolor` as a system property to colorize terminal outputs.
2019-01-18 04:39:33 -05:00
### Examples
2020-10-14 10:13:17 +08:00
The following examples use [petstore.yaml ](https://raw.githubusercontent.com/openapitools/openapi-generator/master/modules/openapi-generator/src/test/resources/3_0/petstore.yaml ).
2019-01-18 04:39:33 -05:00
#### Additional Properties
Generator-specific options should be passed as `--additional-properties` :
``` bash
2021-03-09 20:14:57 +13:00
openapi-generator-cli generate -g go --additional-properties= prependFormOrBodyParameters = true \
2019-01-18 04:39:33 -05:00
-o out -i petstore.yaml
```
2020-02-26 01:25:00 -05:00
Pass more options via comma delimited key/value pairs:
2019-01-18 04:39:33 -05:00
``` bash
--additional-properties= key1 = value1,key2= value2
```
2020-02-26 01:25:00 -05:00
For the full list of generator-specific parameters, refer to [generators docs ](./generators.md ).
2019-04-05 00:38:33 +02:00
2019-01-18 04:39:33 -05:00
#### Type Mappings and Import Mappings
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` :
``` bash
2021-03-09 20:14:57 +13:00
openapi-generator-cli generate \
2019-01-18 04:39:33 -05:00
-i petstore.yaml \
-g kotlin-spring \
-o out \
2022-04-26 17:03:32 +00:00
--additional-properties= library = spring-boot,beanValidations= true,serviceImplementation= true \
2019-01-18 04:39:33 -05:00
--import-mappings= DateTime = java.time.LocalDateTime \
--type-mappings= DateTime = java.time.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).
2020-08-31 01:44:44 -04:00
#### File Post-Processing
The `--enable-post-process-file` option enables specific generators to invoke some external language-specific formatting script. Each filename is passed _ individually _ to this external script, allowing for linting, formatting, or other custom clean-up.
For more details, see [File Post-Processing ](./file-post-processing.md ).
2019-01-18 04:39:33 -05:00
### 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:
``` bash
--import-mappings= Pet = com.yourpackage.models.Pet,User= com.yourpackage.models.User
```
#### Configuration File
2019-03-18 15:49:45 +02:00
Rather than passing generator options in a CSV of `--additional-properties` , you may also provide the settings via JSON file or YAML file.
2019-01-18 04:39:33 -05:00
For example, one of our typescript samples has the following configuration file:
``` json
{
"npmName" : "@swagger/typescript-fetch-petstore" ,
"npmVersion" : "1.0.0" ,
"npmRepository" : "https://skimdb.npmjs.com/registry" ,
"snapshot" : false ,
"supportsES6" : true
}
```
These settings can be passed via `-c filename` . Here, we've saved the above as `config.json` :
``` bash
2021-03-09 20:14:57 +13:00
openapi-generator-cli generate -i petstore.yaml -g typescript-fetch -o out \
2019-01-18 04:39:33 -05:00
-c config.json
```
2019-03-18 15:49:45 +02:00
Same configuration file can be passed into YAML format having following equivalent content:
``` yaml
npmName : "@swagger/typescript-fetch-petstore"
npmVersion : "1.0.0"
npmRepository : "https://skimdb.npmjs.com/registry"
snapshot : false
supportsES6 : true
```
The settings are passed exactly the same as for `config.json` . The most important part is the file extension. Supported values are `yml` or `yaml` .
2022-11-08 00:30:24 +11:00
The name of the file should be `config.yml` or `config.yaml` (in our example it will be `config.yaml` ).
2019-03-18 15:49:45 +02:00
``` bash
2021-03-09 20:14:57 +13:00
openapi-generator-cli generate -i petstore.yaml -g typescript-fetch -o out \
2019-03-18 15:49:45 +02:00
-c config.yaml
```
2019-11-21 22:09:08 -05:00
## batch
The `batch` command allows you to move all CLI arguments supported by the `generate` command into a YAML or JSON file.
* NOTE * : This command supports an additional `!include` property which may point to another "shared" file, the base path to which can be
2023-02-17 09:44:13 -06:00
modified by `--includes-base-dir` . Starting with 5.0.0, the `!batch` command supports multiple `!include` properties, either sequential or nested under other keys. In order to support multiple `!include` properties in a JSON file, the property name can have a suffix, e.g. `!include1` , `!include2` , etc. The suffix have no meaning other than providing unique property names.
2019-11-21 22:09:08 -05:00
2021-04-03 05:28:25 +02:00
``` text
2021-03-09 20:14:57 +13:00
openapi-generator-cli help batch
2019-11-21 22:09:08 -05:00
NAME
openapi-generator-cli batch - Generate code in batch via external
configs.
SYNOPSIS
2021-04-03 05:28:25 +02:00
openapi-generator-cli batch [--clean] [--fail-fast]
2019-11-21 22:09:08 -05:00
[--includes-base-dir <includes>] [(-r <threads> | --threads <threads>)]
[--root-dir <root>] [--timeout <timeout>] [(-v | --verbose)] [--]
<configs>...
OPTIONS
2021-04-03 05:28:25 +02:00
--clean
clean output of previously written files before generation
2019-11-21 22:09:08 -05:00
--fail-fast
fail fast on any errors
--includes-base-dir <includes>
base directory used for includes
-r <threads>, --threads <threads>
thread count
--root-dir <root>
root directory used output/includes (includes can be overridden)
--timeout <timeout>
execution timeout (minutes)
-v, --verbose
verbose mode
--
This option can be used to separate command-line options from the
list of argument, (useful when arguments might be mistaken for
command-line options
<configs>
Generator configuration files.
```
Example:
``` bash
# create "shared" config
mkdir shared && cat > shared/common.yaml <<EOF
2020-10-14 10:13:17 +08:00
inputSpec: https://raw.githubusercontent.com/OpenAPITools/openapi-generator/master/modules/openapi-generator/src/test/resources/3_0/petstore.yaml
2019-11-21 22:09:08 -05:00
additionalProperties:
x-ext-name: "Your Name"
EOF
2023-02-17 09:44:13 -06:00
# create nested "shared" config
cat > shared/nested.yaml <<EOF
useCompareNetObjects: "true"
EOF
2019-11-21 22:09:08 -05:00
# create "standard" configs
cat > kotlin.yaml <<EOF
'!include': 'shared/common.yaml'
outputDir: out/kotlin
generatorName: kotlin
artifactId: kotlin-petstore-string
additionalProperties:
dateLibrary: string
serializableModel: "true"
EOF
cat > csharp.yaml <<EOF
'!include': 'shared/common.yaml'
outputDir: out/csharp-netcore
generatorName: csharp-netcore
additionalProperties:
packageGuid: "{321C8C3F-0156-40C1-AE42-D59761FB9B6C}"
2023-02-17 09:44:13 -06:00
'!include': 'shared/nested.yaml'
2019-11-21 22:09:08 -05:00
EOF
# Generate them
2021-03-09 20:14:57 +13:00
openapi-generator-cli batch *.yaml
2019-11-21 22:09:08 -05:00
```
2020-02-11 08:22:58 -05:00
2020-05-28 00:12:59 -04:00
## author
This command group contains utilities for authoring generators or customizing templates.
2021-04-03 05:28:25 +02:00
``` text
2021-03-09 20:14:57 +13:00
openapi-generator-cli help author
2020-05-28 00:12:59 -04:00
NAME
openapi-generator-cli author - Utilities for authoring generators or
customizing templates.
SYNOPSIS
openapi-generator-cli author
2021-04-03 05:28:25 +02:00
openapi-generator-cli author template [--library <library>]
[(-v | --verbose)]
2020-05-28 00:12:59 -04:00
[(-o <output directory> | --output <output directory>)]
(-g <generator name> | --generator-name <generator name>)
OPTIONS
--help
Display help about the tool
--version
Display full version output
COMMANDS
With no arguments, Display help information about openapi-generator
template
Retrieve templates for local modification
2021-04-03 05:28:25 +02:00
With --library option, library template (sub-template)
2020-05-28 00:12:59 -04:00
With --verbose option, verbose mode
With --output option, where to write the template files (defaults to
'out')
With --generator-name option, generator to use (see list command for
list)
```
### template
This command allows user to extract templates from the CLI jar which simplifies customization efforts.
2021-04-03 05:28:25 +02:00
``` text
openapi-generator-cli help author template
2020-05-28 00:12:59 -04:00
NAME
openapi-generator-cli author template - Retrieve templates for local
modification
SYNOPSIS
openapi-generator-cli author template
(-g <generator name> | --generator-name <generator name>)
[--library <library>]
[(-o <output directory> | --output <output directory>)]
[(-v | --verbose)]
OPTIONS
-g <generator name>, --generator-name <generator name>
generator to use (see list command for list)
--library <library>
library template (sub-template)
-o <output directory>, --output <output directory>
where to write the template files (defaults to 'out')
-v, --verbose
verbose mode
```
Example:
Extract Java templates, limiting to the `webclient` library.
2021-04-03 05:28:25 +02:00
``` bash
2021-03-09 20:14:57 +13:00
openapi-generator-cli author template -g java --library webclient
2020-05-28 00:12:59 -04:00
```
Extract all Java templates:
2021-04-03 05:28:25 +02:00
``` bash
2021-03-09 20:14:57 +13:00
openapi-generator-cli author template -g java
2020-05-28 00:12:59 -04:00
```
