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.

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]
    [DOCUMENTATION_OUTPUT_DIRECTORY <dir>]
    [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.

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 enables generation of doxygen documentation for generated classes.
• DOCUMENTATION_OUTPUT_DIRECTORY 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.

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
)