Revision control
Copy as Markdown
// Copyright (C) 2025 The Qt Company Ltd.
// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
/*!
\group cmake-commands-qtopenapi
\title CMake Commands in Qt6 OpenApi
\brief Lists CMake commands defined in Qt6::OpenApiTools.
The following CMake commands are defined when Qt6::OpenApiTools
is loaded with:
\code
find_package(Qt6 REQUIRED COMPONENTS OpenApiTools)
\endcode
\sa {CMake Command Reference}
*/
/*!
\page qt-add-openapi-client.html
\ingroup cmake-commands-qtopenapi
\title qt_add_openapi_client
\target qt_add_openapi_client
\keyword qt6_add_openapi_client
\summary {Generates an HTTP client using a provided OpenAPI specification.}
\include cmake-find-package-qtopenapi.qdocinc
\cmakecommandsince 6.11
\preliminarycmakecommand
\section1 Synopsis
\code
qt_add_openapi_client(target
SPEC_FILE filename.yaml
)
\endcode
\versionlessCMakeCommandsNote qt6_add_openapi_client()
\section1 Description
The \c 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 \c qt_add_library
or \c qt_add_executable functions.
\note Always create the target before calling the \c qt_add_openapi_client
function.
\badcode
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>]
)
\endcode
\note Only \c client code generation is currently supported.
\section1 Arguments
\list
\li \c {SPEC_FILE}
specifies an OpenAPI specification file, mandatory for code
generation.
The file should have a \c {*.yaml} extension.
\li \c {OUTPUT_DIRECTORY}
specifies the output directory for the generated code.
When not specified, \c CMAKE_CURRENT_BINARY_DIR is used.
\li \c {ADDITIONAL_PROPERTIES}
specifies additional configuration properties for the generate command.
They are passed as-is to the OpenAPI Generator without validation.
\li \c {GENERATE_OPTIONS}
specifies extra options passed to the
command.
The \c -i and \c --input-spec arguments passed through
\c GENERATE_OPTIONS will be ignored. The OpenAPI specification file is
exclusively set using \c SPEC_FILE argument.
The \c -o and \c --output arguments passed through \c GENERATE_OPTIONS
will be ignored. The output directory is exclusively set using the
\c OUTPUT_DIRECTORY argument.
\li \c {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.
\li \c {GENERATE_DOCUMENTATION}
enables generation of \c doxygen documentation for generated
classes.
\li \c {DOCUMENTATION_OUTPUT_DIRECTORY}
specifies a directory that will store the \c doxygen documentation.
The option can only be used together with \c {GENERATE_DOCUMENTATION}.
\li \c {OUTPUT_PUBLIC_HEADERS_DIR}
specifies a directory that will store the list of generated public
headers, otherwise you can find headers in the \c {OUTPUT_DIRECTORY}.
\li \c {OUTPUT_PRIVATE_HEADERS_DIR}
specifies a directory that will store the list of generated private
headers, otherwise you can find headers in the \c {OUTPUT_DIRECTORY}.
\endlist
\section2 Customizing generation behavior
The \c GENERATE_OPTIONS and \c 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:
\code
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
)
\endcode
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:
\list
\li Using the \c ADDITIONAL_PROPERTIES argument.
\li Passing \c -p or \c --additional-properties in the \c GENERATE_OPTIONS
argument.
\endlist
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 \c packageName additional property corresponds to the
function's \c <target> parameter and cannot be modified.
\section3 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 \c JAVA_OPTIONS:
\code
qt6_add_openapi_client(ClientExample
SPEC_FILE
${CMAKE_CURRENT_SOURCE_DIR}/example.yaml
JAVA_OPTIONS
-DmaxYamlCodePoints=99999999
-Dlog.level=warn
)
\endcode
*/