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]
    [DOCUMENTATION_OUTPUT_DIRECTORY <dir>]
    [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 指定生成命令的其他配置属性。这些属性将按原样传递给 OpenAPI 生成器，无需验证。
• GENERATE_OPTIONS 指定传递给生成命令的额外选项。

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

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

• JAVA_OPTIONS 指定调用 OpenAPI 生成器时传递给 JVM 的其他选项。使用该选项可配置 JVM 行为。选项将按原样传递，无需验证。
• GENERATE_DOCUMENTATION 启用为生成的类生成doxygen 文档。
• DOCUMENTATION_OUTPUT_DIRECTORY 指定存储doxygen 文档的目录。该选项只能与GENERATE_DOCUMENTATION 一起使用。
• OUTPUT_PUBLIC_HEADERS_DIR 指定一个存放生成的公共头文件列表的目录，否则您可以在OUTPUT_DIRECTORY.
• OUTPUT_PRIVATE_HEADERS_DIR 指定一个存放生成的私有头文件列表的目录，否则您可以在OUTPUT_DIRECTORY.

自定义生成行为

GENERATE_OPTIONS 和ADDITIONAL_PROPERTIES 参数可让你自定义上游 OpenAPI 生成器和 Qt XML 生成器插件的行为。

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

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 生成器版本，不同版本之间可能会有变化。

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

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

同时使用这两种方法可能会导致意想不到的结果。我们建议选择一种方法。

自定义 JVM 行为

下面的示例展示了如何使用JAVA_OPTIONS 增加 YAML 解析器对大型规范文件的限制，并将日志输出减少到仅警告：

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