OpenAPI Generator Setup: Installation and Configuration Guide
In this tutorial, you will learn about OpenAPI Generator Setup: Installation and Configuration Guide. We cover key concepts, practical examples, and best practices to help you master this topic.
OpenAPI Generator can be installed as CLI, Maven/Gradle plugins, Docker image, npm package, or Homebrew, with configuration via command-line options, config files, and per-generator settings.
What You'll Learn
How to install OpenAPI Generator via multiple methods (CLI, Maven, Gradle, Docker, npm), validate the installation, configure generation with a YAML config file, set per-generator options, and verify setup with a sample spec.
Why It Matters
Choosing the right installation method for your stack simplifies integration. Maven/Gradle plugins for Java projects, npm for Node.js projects, Docker for CI/CD. DodaTech uses the Docker image in CI and the Maven plugin for Spring Boot projects.
Real-World Use
A Java team adds OpenAPI Generator to their Spring Boot project via Maven plugin. On every build, the plugin reads the OpenAPI spec, generates server stubs, and compiles them with the custom code — no manual steps.
flowchart LR
A["Installation\nMethod"] --> B["CLI\nManual/CI"]
A --> C["Maven Plugin\nJava Projects"]
A --> D["Gradle Plugin\nJava/Kotlin"]
A --> E["Docker\nCI/CD"]
A --> F["npm\nNode.js"]
B --> G["Validate Setup\nwith hello"]
C --> G
D --> G
E --> G
F --> G
G --> H["Ready to\nGenerate"]
style A fill:#6cb4ee,color:#fff
style H fill:#bbf7d0,stroke:#16a34a
Installation Methods
# Method 1: Homebrew (macOS)
brew install openapi-generator
openapi-generator version
# Expected: 7.5.0
# Method 2: npm (Node.js)
npm install @openapitools/openapi-generator-cli -g
openapi-generator-cli version
# Method 3: Docker
docker pull openapitools/openapi-generator-cli
docker run openapitools/openapi-generator-cli version
# Method 4: JAR (any platform)
wget https://repo1.maven.org/maven2/org/openapitools/openapi-generator-cli/7.5.0/openapi-generator-cli-7.5.0.jar -O openapi-generator-cli.jar
java -jar openapi-generator-cli.jar version
# Method 5: Maven (pom.xml)
# See Maven plugin section below
# Method 6: Gradle (build.gradle)
# See Gradle plugin section below
Maven Plugin Configuration
<!-- pom.xml -->
<build>
<plugins>
<plugin>
<groupId>org.openapitools</groupId>
<artifactId>openapi-generator-maven-plugin</artifactId>
<version>7.5.0</version>
<executions>
<execution>
<goals><goal>generate</goal></goals>
<configuration>
<inputSpec>${project.basedir}/src/main/resources/openapi.yaml</inputSpec>
<generatorName>spring</generatorName>
<apiPackage>com.dodatech.api</apiPackage>
<modelPackage>com.dodatech.model</modelPackage>
<invokerPackage>com.dodatech.invoker</invokerPackage>
<configOptions>
<useSpringBoot3>true</useSpringBoot3>
<useJakartaEe>true</useJakartaEe>
<dateLibrary>java8</dateLibrary>
</configOptions>
</configuration>
</execution>
</executions>
</plugin>
</plugins>
</build>
# Run:
# mvn openapi-generator:generate
Gradle Plugin Configuration
// build.gradle
plugins {
id 'org.openapi.generator' version '7.5.0'
}
openApiGenerate {
generatorName = "spring"
inputSpec = "$rootDir/src/main/resources/openapi.yaml"
apiPackage = "com.dodatech.api"
modelPackage = "com.dodatech.model"
invokerPackage = "com.dodatech.invoker"
configOptions = [
useSpringBoot3: "true",
useJakartaEe: "true",
dateLibrary: "java8"
]
}
// Run:
// gradle openApiGenerate
Configuration File
# openapi-generator-config.yaml
# Centralized configuration for generation
inputSpec: ./openapi.yaml
generatorName: python-fastapi
outputDir: ./generated/server
# Package configuration
packageName: dodatech_api_server
projectName: dodatech-api-server
packageVersion: 1.0.0
# API/model package names
apiPackage: dodatech.api
modelPackage: dodatech.models
# Generator-specific options
configOptions:
sortParamsByRequiredFlag: true
sortModelPropertiesByRequiredFlag: true
hideGenerationTimestamp: true
generateSourceCodeOnly: true
useNose: false
# Files to always generate (overwrite)
# Files to ignore (preserve existing)
ignoreFileOverride: .openapi-generator-ignore
# Additional properties
additionalProperties:
variableName: value
# Run with:
# openapi-generator generate -c openapi-generator-config.yaml
Validating Setup
# 1. Check version
openapi-generator version
# 2. List available generators
openapi-generator list | head -20
# Expected:
# --------------- generators available ----------------
# ada | client | ada
# android | client | Android
# aspnetcore | server | ASP.NET Core...
# csharp | client | C#
# dart | client | Dart
# dart-jaguar | client | Dart (jaguar)
# elixir | server | Elixir
# erlang-client | client | Erlang Client
# erlang-proper | server | Erlang Proper
# go | client | Go
# go-gin-server | server | Go Gin server
# graphql-schema | server | GraphQL Schema
# java | client | Java
# 3. Validate a spec
openapi-generator validate -i openapi.yaml
# Expected: ✅ Valid OpenAPI specification
# 4. Generate a sample
openapi-generator generate -i openapi.yaml -g python-flask -o /tmp/test-gen
echo "Setup valid. Generated $(find /tmp/test-gen -name '*.py' | wc -l) Python files"
# Expected:
# Setup valid. Generated 15 Python files
Common Mistakes
1. Installing the Wrong Package
There are two npm packages: @openapitools/openapi-generator-cli (official) and openapi-generator (unrelated). Install the @openapitools scoped package for the official CLI.
2. Not Setting Config Options
Generating without config options produces default output that may not match your conventions. Always set apiPackage, modelPackage, sourceFolder, and language-specific options.
3. Using Incompatible Generator Versions
The generator version should match major versions. 7.x generators produce different output than 6.x. Pin the version and test compatibility before upgrading.
4. Ignoring the Ignore File
Generated files are overwritten every time. Use .openapi-generator-ignore to preserve custom files that should not be regenerated.
5. Running Without Spec Validation
An invalid spec generates broken code. Always validate first: openapi-generator validate -i spec.yaml. Catch spec errors before code generation.
Practice Questions
- What installation methods are supported?
- How do you configure generation with a YAML file?
- What is the .openapi-generator-ignore file for?
- How do you validate an OpenAPI spec?
Answers:
- CLI (Homebrew/JAR), Maven plugin, Gradle plugin, Docker image, npm package. Choose based on your tech stack: Maven for Java, Gradle for Android, Docker for CI, npm for Node.js.
- Create a YAML config file with
inputSpec,generatorName,outputDir,apiPackage,modelPackage, andconfigOptions. Pass with-c config.yaml. .openapi-generator-ignorelists files or patterns that should NOT be overwritten during generation. Use it to preserve custom modifications in generated directories.openapi-generator validate -i spec.yaml. It checks structural validity, reference resolution, and schema correctness. Always validate before generating.
Challenge: Install OpenAPI Generator via 2 different methods, create a minimal OpenAPI spec with 2 endpoints, generate output with both installations, verify the output is identical, create a config YAML file, and set up generation with Maven/Gradle plugin.
FAQ
Mini Project
Install OpenAPI Generator via Docker and CLI, create an OpenAPI spec with 3 endpoints, validate it, generate Python FastAPI and JavaScript client in separate output directories, compare the two outputs, create a config YAML file, and verify the ignore file prevents overwriting.
What's Next
Server Generation — generate server stubs for various frameworks.
Built by the developers of DodaTech
Doda Browser, DodaZIP & Durga Antivirus Pro