qt_add_openapi_client | Qt OpenAPI | Qt 6.12.0
Description: Generates an HTTP client using a provided OpenAPI specification.

- Qt 6.12
- Qt OpenAPI
- CMake Commands in Qt6 OpenApi
- qt_add_openapi_client
- Qt 6.12.0 Reference Documentation

# qt_add_openapi_client

Generates an HTTP client using a provided OpenAPI specification.

The command is defined in the `OpenApiTools` component of the `Qt6` package. Load the package with:

     find_package(Qt6 REQUIRED COMPONENTS OpenApiTools)

This command was introduced in Qt 6.11.

Note: This command is in technology preview and may change in future releases.

## Synopsis

     qt_add_openapi_client(<target>
         SPEC_FILE <file>
         [OUTPUT_DIRECTORY <dir>]
         [ADDITIONAL_PROPERTIES property1=value1 property2=value2 ...]
         [GENERATE_OPTIONS generate_option1 generate_option2 ...]
         [JAVA_OPTIONS jvm_option1 jvm_option2 ...]
         [GENERATE_DOCUMENTATION] # since Qt 6.12
         [DOCUMENTATION_OUTPUT_DIRECTORY <dir>] # since Qt 6.12
         [OUTPUT_PUBLIC_HEADERS_DIR <dir>]
         [OUTPUT_PRIVATE_HEADERS_DIR <dir>]
     )

If versionless commands are disabled, use `qt6_add_openapi_client()` instead. It supports the same set of arguments as this command.

## Description

The `qt_add_openapi_client` function calls the Qt OpenAPI generator for a provided specification file. As a result, the command generates the scope of source files and adds them to the target source list. If the target doesn't exist, the generation will be stopped with an error message. For creating the target you can call `qt_add_library` or `qt_add_executable` functions.

Note: Only `client` code generation is currently supported.

## Arguments

- `SPEC_FILE` specifies an OpenAPI specification file, mandatory for code generation. The file should have a `*.yaml` extension.
- `OUTPUT_DIRECTORY` specifies the output directory for the generated code. When not specified, `CMAKE_CURRENT_BINARY_DIR` is used.
- `ADDITIONAL_PROPERTIES` specifies additional configuration properties for the generate command. They are passed as-is to the OpenAPI Generator without validation.
- `GENERATE_OPTIONS` specifies extra options passed to the generate command.

  The `-i` and `--input-spec` arguments passed through `GENERATE_OPTIONS` will be ignored. The OpenAPI specification file is exclusively set using `SPEC_FILE` argument.

  The `-o` and `--output` arguments passed through `GENERATE_OPTIONS` will be ignored. The output directory is exclusively set using the `OUTPUT_DIRECTORY` argument.

- `JAVA_OPTIONS` specifies additional options passed to the JVM when invoking the OpenAPI Generator. Use this to configure JVM behavior. The options are passed as-is without validation.
- `GENERATE_DOCUMENTATION` (since Qt 6.12) enables generation of `doxygen` documentation for generated classes.
- `DOCUMENTATION_OUTPUT_DIRECTORY` (since Qt 6.12) specifies a directory that will store the `doxygen` documentation. The option can only be used together with `GENERATE_DOCUMENTATION`.
- `OUTPUT_PUBLIC_HEADERS_DIR` specifies a directory that will store the list of generated public headers, otherwise you can find headers in the `OUTPUT_DIRECTORY`.
- `OUTPUT_PRIVATE_HEADERS_DIR` specifies a directory that will store the list of generated private headers, otherwise you can find headers in the `OUTPUT_DIRECTORY`.

### Customizing generation behavior

The `GENERATE_OPTIONS` and `ADDITIONAL_PROPERTIES` arguments let you customize the behavior of both the upstream OpenAPI generator and the Qt generator plugin.

The example below shows how you can use both arguments together in your project:

     qt6_add_openapi_client(ClientExample
         SPEC_FILE
             ${CMAKE_CURRENT_SOURCE_DIR}/example.yaml
         ADDITIONAL_PROPERTIES
             cppNamespace=ExampleNamespace
             modelNamePrefix=Example
         GENERATE_OPTIONS
             --skip-overwrite
             --api-name-suffix MyApiSuffix
     )

The behavior and supported values of generator arguments depend on the installed OpenAPI Generator version and may change between versions.

You can provide additional configuration properties in two ways:

- Using the `ADDITIONAL_PROPERTIES` argument.
- Passing `-p` or `--additional-properties` in the `GENERATE_OPTIONS` argument.

Using both simultaneously may lead to unexpected results. We recommend choosing one approach.

Note: Some additional properties have fixed values that cannot be overridden. If you attempt to override them, your values will be ignored. For example, the `packageName` additional property corresponds to the function's `<target>` parameter and cannot be modified.

#### Customizing JVM behavior

The following example shows how to increase the YAML parser limit for large specification files and reduce log output to warnings only using `JAVA_OPTIONS`:

     qt6_add_openapi_client(ClientExample
         SPEC_FILE
             ${CMAKE_CURRENT_SOURCE_DIR}/example.yaml
         JAVA_OPTIONS
             -DmaxYamlCodePoints=99999999
             -Dlog.level=warn
     )