qt_add_openapi_client

Generates an HTTP client using a provided OpenAPI specification.

This command was introduced in Qt 6.11.

Synopsis

The command is defined in the OpenApiTools component of the Qt6 package, which can be loaded like this:

find_package(Qt6 REQUIRED COMPONENTS OpenApiTools)

qt_add_openapi_client(target
    SPEC_FILE filename.yaml
)

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.

qt_add_openapi_client(<target>
    SPEC_FILE <file>
    [OUTPUT_DIRECTORY <dir>]
    [GENERATE_DOCUMENTATION]
    [DOCUMENTATION_OUTPUT_DIRECTORY <dir>]
    [OUTPUT_PUBLIC_HEADERS_DIR <dir>]
    [OUTPUT_PRIVATE_HEADERS_DIR <dir>]
)

Arguments

• SPEC_FILE specifies an OpenAPI specification file, mandatory for a 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 provide a way to 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 to choose 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
)