qt_add_openapi_client

使用提供的 OpenAPI 规范生成一个 HTTP 客户端。

该命令定义在Qt6 包的OpenApiTools 组件中。使用以下命令加载该包：

find_package(Qt6 REQUIRED COMPONENTS OpenApiTools)

该命令于 Qt 6.11 中引入。

语法

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>]
)

如果禁用了无版本号的命令，请改用 `qt6_add_openapi_client() `。它支持与本命令相同的参数集。

描述

qt_add_openapi_client 函数会针对给定的规范文件调用 Qt OpenAPI 生成器。因此，该命令会生成源文件的范围，并将它们添加到目标源文件列表中。如果目标不存在，生成过程将停止并显示错误消息。要创建该目标，您可以调用qt_add_library 或qt_add_executable 函数。

参数

• SPEC_FILE 指定一个 OpenAPI 规范文件，这是代码生成的必填参数。该文件应具有*.yaml 扩展名。
• OUTPUT_DIRECTORY 指定生成的代码的输出目录。若未指定，则使用CMAKE_CURRENT_BINARY_DIR 。
• ADDITIONAL_PROPERTIES 指定 generate 命令的附加配置属性。这些属性将原样传递给 OpenAPI Generator，不会进行验证。
• GENERATE_OPTIONS 指定传递给generate命令的额外选项。

  通过GENERATE_OPTIONS 传递的-i 和--input-spec 参数将被忽略。OpenAPI规范文件仅通过SPEC_FILE 参数设置。

  通过GENERATE_OPTIONS 传递的-o 和--output 参数将被忽略。输出目录仅通过OUTPUT_DIRECTORY 参数设置。

• JAVA_OPTIONS 指定调用 OpenAPI Generator 时传递给 JVM 的附加选项。使用此选项配置 JVM 的行为。这些选项将原样传递，不进行验证。
• GENERATE_DOCUMENTATION （自 Qt 6.12 起）启用为生成的类生成doxygen 文档。
• DOCUMENTATION_OUTPUT_DIRECTORY （自 Qt 6.12 起）指定用于存储doxygen 文档的目录。该选项必须与GENERATE_DOCUMENTATION 配合使用。
• OUTPUT_PUBLIC_HEADERS_DIR 指定用于存储生成的公共头文件列表的目录，否则可在OUTPUT_DIRECTORY 中找到这些头文件。
• OUTPUT_PRIVATE_HEADERS_DIR 指定用于存储生成的私有头文件列表的目录；否则，可在OUTPUT_DIRECTORY 中找到这些头文件。

自定义生成行为

通过GENERATE_OPTIONS 和ADDITIONAL_PROPERTIES 这两个参数，您可以自定义上游 OpenAPI 生成器以及 Qt 生成器插件的行为。

下面的示例展示了如何在项目中同时使用这两个参数：

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
)

生成器参数的行为和支持的值取决于已安装的 OpenAPI Generator 版本，并且可能会随版本变化而改变。

您可以通过以下两种方式提供额外的配置属性：

• 使用 `ADDITIONAL_PROPERTIES ` 参数。
• 在GENERATE_OPTIONS 参数中传入-p 或--additional-properties 。

同时使用这两种方法可能会导致意外结果。我们建议选择其中一种方法。

自定义 JVM 行为

以下示例演示了如何针对大型规范文件提高 YAML 解析器的限制，并使用 `JAVA_OPTIONS` 将日志输出仅保留为警告：

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