Back to Qt.io
Contact Us Blog Download Qt
本页内容

Qt OpenAPI

Qt OpenAPI模块提供了使用Qt Network RESTful API生成Qt HTTP客户端的功能。该模块的主要功能包括Qt OpenAPI生成器和预生成的OpenApiCommon 库。

QtOpenAPI生成器是OpenAPI生成器的插件。它允许您使用 Qt NetworkQRestAccessManager 等 API 自动生成 Qt HTTP 客户端。

注意：Qt OpenAPI生成器以 OpenAPI 3.1.1规范为参考。这会影响操作参数和可为空的模型属性等功能。

注意： 6.12 版本中的Qt OpenAPI 处于技术预览阶段，其 API 不包含在Qt 的兼容性承诺范围内。

使用该模块

要使用 Qt OpenAPI 模块，必须安装以下软件包：

/note Qt OpenAPI 生成器生成的代码可能因版本而异，因为它取决于当前使用的上游 OpenAPI 生成器的版本。旧版本的生成器可能不支持某些功能。

完成所需安装后，即可在您的项目中使用 Qt OpenAPI 生成器。若要使用 Qt OpenAPI 生成器根据 OpenAPI 规范生成客户端代码，请在项目的 CMakeLists.txt 文件中调用qt_add_openapi_client函数。详情请参阅《使用 CMake 构建》。

使用 CMake 进行构建

使用qt_add_openapi_client 函数

使用find_package() 命令在 Qt6 包中定位所需的模块组件。然后调用qt_add_openapi_client函数来生成所需的 Qt HTTP 客户端库。请参阅下面的完整 CMake 代码示例：

cmake_minimum_required(VERSION 3.22)

project(openapiApplication LANGUAGES CXX)

set(CMAKE_AUTOUIC ON)
set(CMAKE_AUTOMOC ON)
set(CMAKE_AUTORCC ON)

set(CMAKE_CXX_STANDARD 17)
set(CMAKE_CXX_STANDARD_REQUIRED ON)

find_package(Qt6 REQUIRED COMPONENTS Core OpenApiCommon OpenApiTools)

qt_add_executable(openapiApplication
  main.cpp
)
qt_add_library(generatedLibrary)
qt_add_openapi_client(generatedLibrary
    SPEC_FILE
        ${CMAKE_CURRENT_SOURCE_DIR}/spec.yaml
)
target_link_libraries(openapiApplication PRIVATE Qt6::Core generatedLibrary)

include(GNUInstallDirs)
install(TARGETS openapiApplication
    LIBRARY DESTINATION ${CMAKE_INSTALL_LIBDIR}
    RUNTIME DESTINATION ${CMAKE_INSTALL_BINDIR}
)

注意： OpenApiTools 库无需链接到生成的openapiApplication 目标。但它仍是启用qt_add_openapi_clientCMake函数所必需的。

注意： OpenApiCommon 库是通过调用qt_add_openapi_client与目标关联的。

从命令行调用 Qt OpenAPI Generator

若要使用 Qt OpenAPI Generator 从 OpenAPI 规范生成客户端代码，请运行以下命令：

java -cp <path-to-installed-openapigen>/openapi-generator-cli.jar:<path-to-installed-qt>/<qt-version>/libexec/cpp-qt6-client-openapi-generator.jar \
org.openapitools.codegen.OpenAPIGenerator \
generate -g cpp-qt6-client \
--additional-properties=cppCommonNamespace=QtOpenApiCommon,prefix=QOAI \
-o generator_output/ -i file.yaml

上述命令将 Qt OpenAPI 生成器添加到类路径中，使其对上游 OpenAPI 生成器可见，然后调用主类org.openapitools.codegen.OpenAPIGenerator 。将 Qt OpenAPI 生成器的名称cpp-qt6-client 设置为-g 参数，可确保其被找到并调用。

若要从超大 OpenAPI 规范文件生成客户端代码，请在命令行中添加maxYamlCodePoints 选项，如下所示：

java -DmaxYamlCodePoints=99999999 <other arguments>

注意： 若要将预生成的Qt6::OpenApiCommon 库链接到项目中，请务必 添加--additional-properties=cppCommonNamespace=QtOpenApiCommon,prefix=QOAI 选项，因为该库是使用这些参数构建的，若提供不同的值，将会导致编译错误。

生成器会在generator_output 文件夹中创建客户端库。请将generator_output 文件夹添加到项目中，如下例所示：

find_package(Qt6 REQUIRED COMPONENTS Core OpenApiCommon)
add_subdirectory(generator_output/client)
add_executable(example_binary
  main.cpp
)
target_link_libraries(Qt6OpenAPIClient PUBLIC Qt6::OpenApiCommon)
target_link_libraries(example_binary PRIVATE Qt6::Core Qt6OpenAPIClient)

若要查看所有生成选项，可使用config-help 选项，如下所示：

java -cp <path-to-installed-openapigen>/openapi-generator-cli.jar:<path-to-installed-qt>/<qt-version>/libexec/cpp-qt6-client-openapi-generator.jar \
org.openapitools.codegen.OpenAPIGenerator config-help -g cpp-qt6-client

注意： 有关生成器的使用方法，请 参阅OpenAPI 生成器文档。

安全注意事项

在使用 Qt OpenAPI 时，请考虑以下与安全相关的方面：

示例

参考

本模块提供的是构建工具（CMake 命令），而非运行时 C++ API。有关可用命令，请参阅Qt6 OpenAPI 中的 CMake 命令。

许可与归属

Qt OpenAPI 模块的不同部分采用不同的许可证。

Qt OpenApiCommon 库由The Qt Company 提供商业许可。此外，该库还遵循GNU 较少通用公共许可证第 3 版（LGPLv3）或GNU 通用公共许可证第 2 版（GPLv2）。更多详情请参阅Qt 许可条款。

Qt OpenAPI Generator 插件及其用于代码生成的模板文件（扩展名为.mustache ）源自上游 OpenAPI 生成器项目，并根据Apache 许可证 2.0 进行授权。

© 2026 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.