OpenAPI Generator CLI

7.21.0 · active · verified Mon Apr 13

The `openapi-generator-cli` Python package provides a command-line interface (CLI) for the OpenAPI Generator, a robust tool that automatically generates API client libraries (SDKs), server stubs, documentation, and configuration from an OpenAPI Specification (supporting both 2.0 and 3.x). The Python package acts as a thin wrapper around the official Java-based OpenAPI Generator, downloading and executing the appropriate JAR file. It maintains an active development pace, with new versions often released daily to mirror updates in the core Java project, typically including numerous enhancements, bug fixes, and sometimes breaking changes with fallbacks.

Warnings

breaking The OpenAPI Generator project frequently introduces breaking changes, often labeled 'with fallbacks', across its major and even minor releases. These changes can affect various generated languages (e.g., Spring Boot 3.x becoming default, changes in Rust, Go, C# generators). Always review release notes and thoroughly test your generated code after upgrading `openapi-generator-cli` to avoid unexpected behavior or compilation errors.
Fix: Consult the official release notes (e.g., on GitHub) for specific breaking changes and their recommended migration paths. Implement robust testing for generated code.
gotcha The `openapi-generator-cli` is a wrapper around a Java JAR and requires a Java Development Kit (JDK) version 11 or higher to be installed and available on your system's PATH. If Java is not correctly configured, the CLI commands will fail with an error. Alternatively, install with the `[jdk4py]` extra to bundle a Java runtime.
Fix: Ensure JDK 11+ is installed and configured in your system's PATH. Verify with `java -version`. Or, install the Python package with `pip install openapi-generator-cli[jdk4py]`.
gotcha The quality, feature completeness, and ideological approach of generated code can vary significantly between different target languages (e.g., Python, Java, Go) and even between different generators for the same language (e.g., `python` vs `python-flask`). Users have reported instances where generated code does not compile, is outdated for current language versions, or deviates from expected patterns, requiring manual intervention or customization of templates.
Fix: Evaluate the generated code for your specific target language and framework. Consider custom templates or post-generation processing if the default output doesn't meet your needs. Be prepared for potential manual adjustments.
gotcha When using `openapi-generator-cli`, especially via the NPM wrapper (which the Python package behaves similarly to in terms of configuration), an `openapitools.json` file is generated. This file manages the downloaded OpenAPI Generator JAR version and specific generation configurations. It is crucial to include this file in your version control system (VCS) to ensure consistent generator versions and settings across different developer environments and CI/CD pipelines.
Fix: Add `openapitools.json` to your `.gitignore` if you are managing the version and config manually, or ensure it is committed to VCS to maintain consistency across team members and deployment environments.

Install

pip install openapi-generator-cli Install base package
pip install openapi-generator-cli[jdk4py] Install with `jdk4py` (embeds Java runtime)

Quickstart

This quickstart demonstrates how to install the `openapi-generator-cli` and use it to generate a Python client library from a public OpenAPI Specification. The `openapi-generator-cli` itself is a command-line tool, and direct Python imports are not typically used for the generator. Instead, you execute the CLI command to produce source code (e.g., an SDK) in a chosen language, which you then integrate into your project and import as a separate library. Replace `https://petstore.swagger.io/v2/swagger.json` with your own OpenAPI spec URL or file path, and adjust the generator (`-g python`) and output directory (`-o my_python_client`) as needed. The commented Python code provides an example of how a *generated* Python client might be used.

pip install openapi-generator-cli

# Check installed version
openapi-generator-cli version

# Generate a Python client from a public OpenAPI specification
# This will create a directory named 'my_python_client' containing the generated SDK
openapi-generator-cli generate \
  -i https://petstore.swagger.io/v2/swagger.json \
  -g python \
  -o my_python_client

# To use the generated client (example, assuming 'my_python_client' was created):
# cd my_python_client
# pip install .
#
# Then in a Python script:
# from openapi_client import api_client, configuration
# from openapi_client.api import pet_api
#
# # Configure API key authorization: api_key
# config = configuration.Configuration()
# config.api_key['api_key'] = 'YOUR_API_KEY_HERE'
#
# # Create an API client
# client = api_client.ApiClient(configuration=config)
# api = pet_api.PetApi(client)
#
# # Example: List pets (assuming the generated client structure)
# # try:
# #     all_pets = api.find_pets_by_status(status=['available'])
# #     print(all_pets)
# # except Exception as e:
# #     print(f"Error: {e}")

view raw JSON →