// 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 <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>]
    )
\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 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
        \l {https://openapi-generator.tech/docs/usage/#generate}{generate}
        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} (since Qt 6.12)
        enables generation of \c doxygen documentation for generated
        classes.
    \li \c {DOCUMENTATION_OUTPUT_DIRECTORY} (since Qt 6.12)
        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
*/
