diff --git a/docs/building.md b/docs/building.md new file mode 100644 index 00000000000..aa029b4cb66 --- /dev/null +++ b/docs/building.md @@ -0,0 +1,76 @@ +--- +id: contribute-building +title: Building the code +--- + +## Using Maven + +To build from source, you need the following installed and available in your `$PATH:` + +* [Java 8](http://java.oracle.com) + +* [Apache maven 3.3.4 or greater](http://maven.apache.org/) + +After cloning the project, you can build it from source with this command: + +```bash +mvn clean install +``` + +If you don't have maven installed, you may directly use the included [maven wrapper](https://github.com/takari/maven-wrapper), and build with the command: + +```bash +./mvnw clean install +``` + +## Using Docker + +You can use `run-in-docker.sh` to do all development. This script maps your local repository to `/gen` +in the docker container. It also maps `~/.m2/repository` to the appropriate container location. + +To execute `mvn package`: + +```bash +git clone https://github.com/openapitools/openapi-generator +cd openapi-generator +./run-in-docker.sh mvn package +``` + +Build artifacts are now accessible in your working directory. + +Once built, `run-in-docker.sh` will act as an executable for openapi-generator-cli. To generate code, you'll need to output to a directory under `/gen` (e.g. `/gen/out`). For example: + +```bash +./run-in-docker.sh help # Executes 'help' command for openapi-generator-cli +./run-in-docker.sh list # Executes 'list' command for openapi-generator-cli +./run-in-docker.sh /gen/bin/go-petstore.sh # Builds the Go client +./run-in-docker.sh generate -i modules/openapi-generator/src/test/resources/2_0/petstore.yaml \ + -g go -o /gen/out/go-petstore -DpackageName=petstore # generates go client, outputs locally to ./out/go-petstore +``` + +### Docker in Vagrant + +Prerequisite: install [Vagrant](https://www.vagrantup.com/downloads.html) and [VirtualBox](https://www.virtualbox.org/wiki/Downloads). + +```bash +git clone http://github.com/openapitools/openapi-generator.git +cd openapi-generator +vagrant up +vagrant ssh +cd /vagrant +./run-in-docker.sh mvn package +``` + +### Troubleshooting + +If an error like this occurs, just execute the **mvn clean install -U** command: + +> org.apache.maven.lifecycle.LifecycleExecutionException: Failed to execute goal org.apache.maven.plugins:maven-surefire-plugin:2.19.1:test (default-test) on project openapi-generator: A type incompatibility occurred while executing org.apache.maven.plugins:maven-surefire-plugin:2.19.1:test: java.lang.ExceptionInInitializerError cannot be cast to java.io.IOException + +```bash +./run-in-docker.sh mvn clean install -U +``` + +> Failed to execute goal org.fortasoft:gradle-maven-plugin:1.0.8:invoke (default) on project openapi-generator-gradle-plugin-mvn-wrapper: org.gradle.tooling.BuildException: Could not execute build using Gradle distribution 'https://services.gradle.org/distributions/gradle-4.7-bin.zip' + +Right now: no solution for this one :| diff --git a/docs/conduct.md b/docs/conduct.md index 3f00ddca67f..dfaf2b72b7d 100644 --- a/docs/conduct.md +++ b/docs/conduct.md @@ -1,6 +1,6 @@ --- id: code-of-conduct -title: Contributor Covenant Code of Conduct +title: Code of Conduct --- ## Our Pledge diff --git a/docs/contributing.md b/docs/contributing.md index 1b6f68801f2..a23ab1b7cb6 100644 --- a/docs/contributing.md +++ b/docs/contributing.md @@ -1,6 +1,7 @@ --- id: contributing title: Guidelines For Contributing +sidebar_label: Guidelines --- ## Before submitting an issue diff --git a/docs/installation.md b/docs/installation.md new file mode 100644 index 00000000000..64335db08f8 --- /dev/null +++ b/docs/installation.md @@ -0,0 +1,148 @@ +--- +id: installation +title: CLI Installation +--- + +There are a number of ways to use OpenAPI Generator. This page documents how to install the CLI artifact. +Installing OpenAPI Generator's CLI tool allows users to generate all available generators from the command line. + +Some of the following are cross-platform options and some are not, these are called out where possible. + +## NPM + +> **Platform(s)**: Linux, macOS, Windows + +The [NPM package wrapper](https://github.com/openapitools/openapi-generator-cli) is cross-platform wrapper around the .jar artifact. It works by providing a CLI wrapper atop the JAR's command line options. This gives a simple interface layer which normalizes usage of the command line across operating systems, removing some differences in how options or switches are passed to the tool (depending on OS). +**Install** the latest version of the tool globally, exposing the CLI on the command line: + +```bash +npm install @openapitools/openapi-generator-cli -g +``` + +To install a specific version of the tool, pass the version during installation: + +```bash +npm install @openapitools/openapi-generator-cli@cli-3.3.4 -g +``` + +To install the tool as a dev dependency in your current project: + +```bash +npm install @openapitools/openapi-generator-cli -D +``` +Then, **generate** a ruby client from a valid [petstore.yaml](https://raw.githubusercontent.com/openapitools/openapi-generator/master/modules/openapi-generator/src/test/resources/2_0/petstore.yaml) doc: + +```bash +npx openapi-generator generate -i petstore.yaml -g ruby -o /tmp/test/ +``` + +> `npx` will execute a globally available `openapi-generator`, and if not found it will fall back to project-local commands. The result is that the above command will work regardless of which installation method you've chosen. + +## Homebrew + +> **Platform(s)**: macOS + +**Install** via [homebrew](https://brew.sh/): + +```bash +brew install openapi-generator +``` + +Then, **generate** a ruby client from a valid [petstore.yaml](https://raw.githubusercontent.com/openapitools/openapi-generator/master/modules/openapi-generator/src/test/resources/2_0/petstore.yaml) doc: + +```bash +openapi-generator generate -i petstore.yaml -g ruby -o /tmp/test/ +``` + +## Docker + +> **Platform(s)**: Linux, macOS, Windows + +The OpenAPI Generator Docker image acts as a standalone executable. It can be used as an alternative to installing via homebrew, or for developers who are unable to install Java or upgrade the installed version. + +To generate code from a valid [petstore.yaml](https://raw.githubusercontent.com/openapitools/openapi-generator/master/modules/openapi-generator/src/test/resources/2_0/petstore.yaml) doc with this image, you'll need to mount a local location as a volume. +You'll then need to output the generated code to this mapped volume. Everything else works the same as if you ran the command on your host machine. + +Here's an example generating a Go client: + +```bash +docker run --rm \ + -v ${PWD}:/local openapitools/openapi-generator-cli generate \ + -i petstore.yaml \ + -g go \ + -o /local/out/go +``` + +## JAR + +> **Platform(s)**: Linux, macOS, Windows + +If you're looking for the latest stable version, you can grab it directly from Maven.org (Java 8 runtime at a minimum): + +JAR location: `http://central.maven.org/maven2/org/openapitools/openapi-generator-cli/3.3.4/openapi-generator-cli-3.3.4.jar` + +For **Mac/Linux** users: + +```bash +wget http://central.maven.org/maven2/org/openapitools/openapi-generator-cli/3.3.4/openapi-generator-cli-3.3.4.jar -O openapi-generator-cli.jar +``` + +For **Windows** users, you will need to install [wget](http://gnuwin32.sourceforge.net/packages/wget.htm) or you can use Invoke-WebRequest in PowerShell (3.0+), e.g. + +``` +Invoke-WebRequest -OutFile openapi-generator-cli.jar http://central.maven.org/maven2/org/openapitools/openapi-generator-cli/3.3.4/openapi-generator-cli-3.3.4.jar +``` + +After downloading the JAR, run `java -jar openapi-generator-cli.jar help` to show the usage. + +For Mac users, please make sure Java 8 is installed (Tips: run `java -version` to check the version), and export `JAVA_HOME` in order to use the supported Java version: + +```bash +export JAVA_HOME=`/usr/libexec/java_home -v 1.8` +export PATH=${JAVA_HOME}/bin:$PATH +``` + +## Bash Launcher Script + +> **Platform(s)**: Linux, macOS, Windows (variable) + +One downside to manual JAR downloads is that you don't keep up-to-date with the latest released version. We have a Bash launcher script at [bin/utils/openapi-generator.cli.sh](https://raw.githubusercontent.com/OpenAPITools/openapi-generator/master/bin/utils/openapi-generator-cli.sh) which solves this problem. + +To install the launcher script, copy the contents of the script to a location on your path and make the script executable. + +An example of setting this up (NOTE: Always evaluate scripts curled from external systems before executing them). + +```bash +mkdir -p ~/bin/openapitools +curl https://raw.githubusercontent.com/OpenAPITools/openapi-generator/master/bin/utils/openapi-generator-cli.sh > ~/bin/openapitools/openapi-generator-cli +chmod u+x ~/bin/openapitools/openapi-generator-cli +export PATH=$PATH:~/bin/openapitools/ +``` + +Now, `openapi-generator-cli` is "installed". On invocation, it will query the GitHub repository for the most recently released version. If this matches the last downloaded jar, +it will execute as normal. If a newer version is found, the script will download the latest release and execute it. + +If you need to invoke an older version of the generator, you can define the variable `OPENAPI_GENERATOR_VERSION` either ad hoc or globally. You can export this variable if you'd like to persist a specific release version. + +Examples: + +```bash +# Execute latest released openapi-generator-cli +openapi-generator-cli version + +# Execute version 3.1.0 for the current invocation, regardless of the latest released version +OPENAPI_GENERATOR_VERSION=3.1.0 openapi-generator-cli version + +# Execute version 3.1.0-SNAPSHOT for the current invocation +OPENAPI_GENERATOR_VERSION=3.1.0-SNAPSHOT openapi-generator-cli version + +# Execute version 3.0.2 for every invocation in the current shell session +export OPENAPI_GENERATOR_VERSION=3.0.2 +openapi-generator-cli version # is 3.0.2 +openapi-generator-cli version # is also 3.0.2 + +# To "install" a specific version, set the variable in .bashrc/.bash_profile +echo "export OPENAPI_GENERATOR_VERSION=3.0.2" >> ~/.bashrc +source ~/.bashrc +openapi-generator-cli version # is always 3.0.2, unless any of the above overrides are done ad hoc +``` diff --git a/docs/online-openapi-generator.md b/docs/online-openapi-generator.md deleted file mode 100644 index 4b981bf32db..00000000000 --- a/docs/online-openapi-generator.md +++ /dev/null @@ -1,91 +0,0 @@ ---- -id: openapi-generator-online -title: Online OpenAPI Generator ---- - -One can also generate API clients or server stubs using the online openapi-generator. - -Here are the public online services: - -- latest stable version: http://api.openapi-generator.tech -- latest master: http://api-latest-master.openapi-generator.tech (updated with latest master every hour) - -The server is sponsored by [Linode](https://www.linode.com/) [![Linode Logo](https://www.linode.com/media/images/logos/standard/light/linode-logo_standard_light_small.png)](https://www.linode.com/) - -(These services are beta and do not have any guarantee on service level) - -If you prefer to run the service locally, here are the steps: -``` -mvn clean install -cd modules/openapi-generator-online -mvn spring-boot:run -``` - -:bulb: The online openapi-generator can be run via [Docker](https://github.com/OpenAPITools/openapi-generator#16---docker) as well. - -For example, to generate Ruby API client, simply send the following HTTP request using curl: -```sh -curl -X POST -H "content-type:application/json" -d '{"openAPIUrl":"https://raw.githubusercontent.com/openapitools/openapi-generator/master/modules/openapi-generator/src/test/resources/2_0/petstore.yaml"}' http://localhost:8080/api/gen/clients/ruby -``` -Then you will receieve a JSON response with the URL to download the zipped code. - -To customize the SDK, you can `POST` to `http://localhost:8080/gen/clients/{language}` with the following HTTP body: -```json -{ - "options": {}, - "openAPIUrl": "https://raw.githubusercontent.com/openapitools/openapi-generator/master/modules/openapi-generator/src/test/resources/2_0/petstore.yaml" -} -``` -in which the `options` for a language can be obtained by submitting a `GET` request to `http://locahost:8080/api/gen/clients/{language}`: - -For example, `curl http://localhost:8080/api/gen/clients/python` returns -```json - "packageName":{ - "opt":"packageName", - "description":"python package name (convention: snake_case).", - "type":"string", - "default":"openapi_client" - }, - "packageVersion":{ - "opt":"packageVersion", - "description":"python package version.", - "type":"string", - "default":"1.0.0" - }, - "sortParamsByRequiredFlag":{ - "opt":"sortParamsByRequiredFlag", - "description":"Sort method arguments to place required parameters before optional parameters.", - "type":"boolean", - "default":"true" - } - -{} -``` -To set package name to `pet_store`, the HTTP body of the request is as follows: -```json -{ - "options": { - "packageName": "pet_store" - }, - "openAPIUrl": "https://raw.githubusercontent.com/openapitools/openapi-generator/master/modules/openapi-generator/src/test/resources/2_0/petstore.yaml" -} -``` -and here is the curl command: -```sh -curl -H "Content-type: application/json" -X POST -d '{"options": {"packageName": "pet_store"},"openAPIUrl": "https://raw.githubusercontent.com/openapitools/openapi-generator/master/modules/openapi-generator/src/test/resources/2_0/petstore.yaml"}' http://localhost:8080/api/gen/clients/python -``` - -Instead of using `openAPIUrl` with an URL to the OpenAPI spec, one can include the spec in the JSON payload with `spec`, e.g. -```json -{ - "options": {}, - "spec": { - "swagger": "2.0", - "info": { - "version": "1.0.0", - "title": "Test API" - }, - ... - } -} -``` \ No newline at end of file diff --git a/docs/online.md b/docs/online.md new file mode 100644 index 00000000000..f5e915dd981 --- /dev/null +++ b/docs/online.md @@ -0,0 +1,146 @@ +--- +id: online +title: Online +--- + +## Hosted + +We offer online services, publicly and free of charge: + +- latest stable version: http://api.openapi-generator.tech +- latest master: http://api-latest-master.openapi-generator.tech (updated with latest master every hour) + +> **Hosting Sponsor** +> [![Linode Logo](https://www.linode.com/media/images/logos/standard/light/linode-logo_standard_light_small.png)](https://www.linode.com/) + +These services are beta and do not have any guarantee on service level + +Please refer to [Online OpenAPI Generator](./online-openapi-generator.md) on how to run and use the `openapi-generator-online` - a web service for `openapi-generator`. + +## Docker Image + +The openapi-generator-online Docker image can act as a self-hosted web application and API for generating code. This container can be incorporated into a CI pipeline, and requires at least two HTTP requests and some docker orchestration to access generated code. + +Example usage: + +```bash +# Start container at port 8888 and save the container id +CID=$(docker run -d -p 8888:8080 \ + -e GENERATOR_HOST=http://localhost:8888 \ + openapitools/openapi-generator-online) + +# allow for startup +sleep 10 + +# Get the IP of the running container (optional) +GEN_IP=$(docker inspect --format '{{.NetworkSettings.IPAddress}}' ${CID}) + +# Execute an HTTP request to generate a Ruby client +curl -X POST --header 'Content-Type: application/json' \ + --header 'Accept: application/json' \ + -d '{"openAPIUrl": "https://raw.githubusercontent.com/openapitools/openapi-generator/master/modules/openapi-generator/src/test/resources/2_0/petstore.yaml"}' \ + 'http://localhost:8888/api/gen/clients/ruby' + +# Example output: +# {"code":"c2d483.3.4672-40e9-91df-b9ffd18d22b8","link":"http://localhost:8888/api/gen/download/c2d483.3.4672-40e9-91df-b9ffd18d22b8"} + +# Download the generated zip file (using "code" provided from your output) +wget http://localhost:8888/api/gen/download/c2d483.3.4672-40e9-91df-b9ffd18d22b8 + +# Unzip the file +unzip c2d483.3.4672-40e9-91df-b9ffd18d22b8 + +# Shutdown the openapi generator image +docker stop ${CID} && docker rm ${CID} +``` + +## Local/Self-hosting + +If you prefer to run the service locally, here are the steps: + +```bash +mvn clean install +cd modules/openapi-generator-online +mvn spring-boot:run +``` + +> The online openapi-generator can be run via [Docker](#docker-image) as well. + +For example, to generate Ruby API client, simply send the following HTTP request using curl: + +```bash +curl -X POST -H "content-type:application/json" -d '{"openAPIUrl":"https://raw.githubusercontent.com/openapitools/openapi-generator/master/modules/openapi-generator/src/test/resources/2_0/petstore.yaml"}' \ + http://localhost:8080/api/gen/clients/ruby +``` +Then you will receive a JSON response with the URL to download the zipped code. + +To customize the SDK, you can `POST` to `http://localhost:8080/gen/clients/{generator}` with the following HTTP body: + +```json +{ + "options": {}, + "openAPIUrl": "https://raw.githubusercontent.com/openapitools/openapi-generator/master/modules/openapi-generator/src/test/resources/2_0/petstore.yaml" +} +``` + +Here, the `options` for a language can be obtained by submitting a `GET` request to `http://locahost:8080/api/gen/clients/{generator}`: + +For example, `curl http://localhost:8080/api/gen/clients/python` returns + +```json + "packageName":{ + "opt":"packageName", + "description":"python package name (convention: snake_case).", + "type":"string", + "default":"openapi_client" + }, + "packageVersion":{ + "opt":"packageVersion", + "description":"python package version.", + "type":"string", + "default":"1.0.0" + }, + "sortParamsByRequiredFlag":{ + "opt":"sortParamsByRequiredFlag", + "description":"Sort method arguments to place required parameters before optional parameters.", + "type":"boolean", + "default":"true" + } + +{} +``` + +To set package name to `pet_store`, the HTTP body of the request is as follows: + +```json +{ + "options": { + "packageName": "pet_store" + }, + "openAPIUrl": "https://raw.githubusercontent.com/openapitools/openapi-generator/master/modules/openapi-generator/src/test/resources/2_0/petstore.yaml" +} +``` + +and here is the curl command: +```bash +curl -H "Content-type: application/json" \ + -X POST \ + -d '{"options": {"packageName": "pet_store"},"openAPIUrl": "https://raw.githubusercontent.com/openapitools/openapi-generator/master/modules/openapi-generator/src/test/resources/2_0/petstore.yaml"}' \ + http://localhost:8080/api/gen/clients/python +``` + +Instead of using `openAPIUrl` with an URL to the OpenAPI spec, one can include the spec in the JSON payload with `spec`: + +```json +{ + "options": {}, + "spec": { + "swagger": "2.0", + "info": { + "version": "1.0.0", + "title": "Test API" + }, + ... + } +} +``` diff --git a/docs/plugins.md b/docs/plugins.md new file mode 100644 index 00000000000..923d1ea24ef --- /dev/null +++ b/docs/plugins.md @@ -0,0 +1,99 @@ +--- +id: plugins +title: Plugins +--- + +## Maven + +A Maven plugin to support the OpenAPI generator project + +### Example + +Add to your `build->plugins` section (default phase is `generate-sources` phase) + +```xml + + org.openapitools + openapi-generator-maven-plugin + 3.3.4 + + + + generate + + + ${project.basedir}/src/main/resources/api.yaml + java + + src/gen/java/main + + + + + +``` + +Followed by: + +```bash +mvn clean compile +``` + +For full details of all options, see the [plugin README](https://github.com/OpenAPITools/openapi-generator/tree/master/modules/openapi-generator-maven-plugin). + +## Gradle + +This gradle plugin offers a declarative DSL via extensions (these are Gradle project extensions). These map almost fully 1:1 with the options you’d pass to the CLI or Maven plugin. The plugin maps the extensions to a task of the same name to provide a clean API. If you’re interested in the extension/task mapping concept from a high-level, you can check out [Gradle’s docs](https://docs.gradle.org/current/userguide/custom_plugins.html#sec:mapping_extension_properties_to_task_properties). + +To include in your project, add the following to `build.gradle`: + +```groovy +buildscript { + repositories { + mavenLocal() + mavenCentral() + } + dependencies { + classpath "org.openapitools:openapi-generator-gradle-plugin:3.3.4" + } +} + +apply plugin: 'org.openapi.generator' +``` + +This gives access to the following tasks: + +| Task | Description | +| ---- | ----------- | +| openApiGenerate | Generate code via Open API Tools Generator for Open API 2.0 or 3.x specification documents. | +| openApiGenerators | Lists generators available via Open API Generators. | +| openApiMeta | Generates a new generator to be consumed via Open API Generator. | +| openApiValidate | Validates an Open API 2.0 or 3.x specification document. | + +> The plugin implements the above tasks as project extensions of the same name. If you’d like to declare these tasks as dependencies to other tasks (using `dependsOn`), you’ll need a task reference. e.g.: +> ```groovy +> compileJava.dependsOn tasks.openApiGenerate +> ``` + +For full details of all options, see the [plugin README](https://github.com/OpenAPITools/openapi-generator/tree/master/modules/openapi-generator-gradle-plugin). + +### Example + +An example task for generating a kotlin client: + +```groovy +openApiGenerate { + generatorName = "kotlin" + inputSpec = "$rootDir/specs/petstore-v3.0.yaml".toString() + outputDir = "$buildDir/generated".toString() + apiPackage = "org.openapi.example.api" + invokerPackage = "org.openapi.example.invoker" + modelPackage = "org.openapi.example.model" + modelFilesConstrainedTo = [ + "Error" + ] + configOptions = [ + dateLibrary: "java8" + ] +} +``` \ No newline at end of file diff --git a/docs/usage.md b/docs/usage.md new file mode 100644 index 00000000000..dd53398a725 --- /dev/null +++ b/docs/usage.md @@ -0,0 +1,475 @@ +--- +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. + +```bash +openapi-generator help +usage: openapi-generator-cli [] + +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 ' 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 + +SYNOPSIS + openapi-generator-cli list [(-s | --short)] + +OPTIONS + -s, --short + shortened output (suitable for scripting) + +``` + +Example: + +```bash +openapi-generator list -s | tr ',' '\n' +``` + +For the full list of generators, refer to the [Generators List](./generators.md). + +## config-help + +The `config-help` option provides details about + +```bash +openapi-generator help config-help +NAME + openapi-generator-cli config-help - Config help for chosen lang + +SYNOPSIS + openapi-generator-cli config-help + [(-f | --format )] + [(-g | --generator-name )] + [--markdown-header] [--named-header] + [(-o | --output )] + +OPTIONS + -f , --format + Write output files in the desired format. Options are 'text' and + 'markdown'. Default is 'text'. + + -g , --generator-name + generator to get config help for + + --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 + 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) + + packageVersion + Go package version. (Default: 1.0.0) + + withGoCodegenComment + whether to include Go codegen comment to disable Go Lint and collapse by default GitHub in PRs and diffs (Default: false) + + 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. + +```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 )] + [(-o | --output )] + [(-p | --package )] [(-t | --type )] + +OPTIONS + -n , --name + the human-readable name of the generator + + -o , --output + where to write the generated files (current dir by default) + + -p , --package + the package to put the main class into (defaults to + org.openapitools.codegen) + + -t , --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). + +```bash +openapi-generator help validate +NAME + openapi-generator-cli validate - Validate specification + +SYNOPSIS + openapi-generator-cli validate + (-i | --input-spec ) [--recommend] + +OPTIONS + -i , --input-spec + 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)): + +```bash +openapi-generator validate -i petstore-v3.0-invalid.yaml +``` +```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 +openapi-generator completion config-help +--named-header +-o +--output +-g +--generator-name +-l +--lang +``` + +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 + +The `generate` command is the workhorse of the generator toolset. As such, it has _many_ more options and the previous commands. The options are abbreviated below, but you may expand the full descriptions. + + +```bash +openapi-generator help generate +NAME + openapi-generator-cli generate - Generate code with the specified + generator. + +SYNOPSIS + openapi-generator-cli generate + [(-a | --auth )] + [--additional-properties ...] + [--api-package ] [--artifact-id ] + [--artifact-version ] + [(-c | --config )] + [-D ...] [--enable-post-process-file] + [(-g | --generator-name )] + [--git-repo-id ] [--git-user-id ] + [--group-id ] [--http-user-agent ] + (-i | --input-spec ) + [--ignore-file-override ] + [--import-mappings ...] + [--instantiation-types ...] + [--invoker-package ] + [--language-specific-primitives ...] + [--library ] [--log-to-stderr] + [--model-name-prefix ] + [--model-name-suffix ] + [--model-package ] + [(-o | --output )] + [--release-note ] [--remove-operation-id-prefix] + [--reserved-words-mappings ...] + [(-s | --skip-overwrite)] [--skip-validate-spec] + [(-t