OpenAPI Generator Options — Complete Reference for Code Generation

In this tutorial, you will learn about OpenAPI Generator Options. We cover key concepts, practical examples, and best practices to help you master this topic.

OpenAPI Generator options control how code is generated, from output paths and package names to language-specific features like async client generation, model prefix conventions, and documentation inclusion.

What You'll Learn

How to use OpenAPI Generator CLI options, configuration files, additionalProperties, globalProperties, and language-specific options to precisely control generated output for any target language or framework.

Why It Matters

Default generation rarely matches your project conventions. Generator options let you configure package names, output structure, import paths, code style, and feature toggles without custom templates. DodaTech uses 20+ options per service to enforce naming conventions and include only needed features.

Real-World Use

DodaTech configures the Python FastAPI generator with options for async endpoints, Pydantic v2 models, snake_case naming, and OpenTelemetry instrumentation. Every generated service follows the same patterns without manual post-processing.

flowchart LR
    A["CLI Options"] --> D["OpenAPI\nGenerator"]
    B["Config File"] --> D
    C["Env Variables"] --> D
    D --> E["Configured\nOutput"]
    subgraph "Options Types"
        F["Generator\nOptions"]
        G["Global\nProperties"]
        H["Additional\nProperties"]
    end
    style D fill:#bbf7d0,stroke:#16a34a
    style E fill:#6cb4ee,color:#fff

CLI Options Reference

Using Additional Properties

# Additional properties control language-specific behavior.
# Common properties:

properties = {
    "packageName": "orders_service",      # Python package name
    "packageVersion": "1.0.0",            # Package version
    "asyncClient": "true",                # Generate async HTTP client
    "usePydanticV2": "true",              # Use Pydantic v2 models
    "sortParamsByRequiredFlag": "true",   # Sort required params first
    "hideGenerationTimestamp": "true",    # Remove timestamp from headers
    "withSeparateModelsAndApi": "true",   # Separate models from API
}

# CLI usage:
cmd = "openapi-generator generate -i openapi.yaml -g python-fastapi -o gen/"
for key, val in properties.items():
    cmd += f" --additional-properties={key}={val}"
print(cmd)
# Expected output:
# openapi-generator generate -i openapi.yaml -g python-fastapi -o gen/
# --additional-properties=packageName=orders_service
# --additional-properties=packageVersion=1.0.0
# --additional-properties=asyncClient=true
# --additional-properties=usePydanticV2=true

Global Properties

# openapi-generator-config.yaml
# Global properties control what is generated:
globalProperties:
  apiDocs: false           # Skip API documentation generation
  apiTests: false          # Skip API test generation
  modelDocs: true          # Generate model documentation
  modelTests: false        # Skip model test generation
  supportingFiles: true    # Generate supporting files

generatorName: python-fastapi
inputSpec: openapi.yaml
outputDir: gen/
additionalProperties:
  packageName: orders_service
  usePydanticV2: true

# Usage:
# openapi-generator generate -c openapi-generator-config.yaml
print("Config file ready. Run the command above to generate.")
# Expected behavior:
# - Generates API handlers without API docs
# - Generates models with documentation
# - Skips all test files
# - Includes Dockerfile, requirements.txt

Language-Specific Options

// Java Spring generator options:
// options = object containing:
options = """
{
  "javaSpring": {
    "interfaceOnly": "true",
    "useTags": "true",
    "useSwaggerUI": "false",
    "basePackage": "com.dodatech.orders",
    "configPackage": "com.dodatech.orders.config",
    "apiPackage": "com.dodatech.orders.api",
    "modelPackage": "com.dodatech.orders.model",
    "dateLibrary": "java8",
    "useOptional": "true"
  }
}
"""
print("Java Spring options set for clean package structure")
# Expected output:
# Options control:
# - interfaceOnly: Generate interfaces, not implementations
# - useTags: Group endpoints by tag
# - basePackage: Root Java package
# - dateLibrary: Use java8 time API

Common Mistakes

1. Case-Sensitive Option Names

Generator option names are case-sensitive. asyncclient: true is silently ignored while asyncClient: true works. Always check the generator's option documentation for exact naming.

2. Options Not Passed Through Config

CLI options have precedence over config file. If an option is set both in the config file and CLI, the CLI value wins. Verify effective options by running with --log-level debug.

3. Forgetting Generator-Specific Defaults

Each generator has different defaults. sortParamsByRequiredFlag may default to false in one generator and true in another. Always explicitly set options you depend on rather than relying on defaults.

4. Boolean Values as Strings

In YAML config files, true must be unquoted boolean, not "true" as a string. String values may be interpreted as truthy strings rather than actual boolean flags.

5. Not Using Config Files for CI

CLI-only options in CI scripts are hard to maintain. Use a config file checked into the Repository for reproducible builds. CI scripts can override specific flags for environment differences.

Practice Questions

1. How do you specify additional properties in the CLI?
2. What is the difference between additionalProperties and globalProperties?
3. How do you skip API documentation generation?
4. Why should you use a config file over CLI flags?

Answers:

1. Use --additional-properties=key=value for each property, or use multiple --additional-properties flags for multiple properties.
2. additionalProperties control language-specific generation behavior (package names, features); globalProperties control what types of files are generated (docs, tests, supporting files).
3. Set globalProperties.apiDocs: false in the config file or use --global-property apiDocs=false in the CLI.
4. Config files are version-controlled, reproducible, and document all options in one place. CLI flags are easy to forget or misconfigure in scripts.

Challenge: Create a configuration file for generating a TypeScript Axios client that uses ES modules, includes model tests, uses a custom API key header, generates separate model files, and skips API documentation. Verify the output matches your expectations.

FAQ

Mini Project

Explore the Python FastAPI generator options using openapi-generator config-help -g python-fastapi, create a config file that enables Pydantic v2, async endpoints, and separate models, generate code from a medium spec (20 endpoints), and verify the output structure matches your expectations.

What's Next

Supported Languages — explore language and framework support.

Configuration & Customization — deep dive into configuration options.