Qt OpenAPI | Qt 6.12.0
Description: A module for generating Qt HTTP clients using OpenAPI and Qt Network RESTful APIs.

- Qt 6.12
- Qt OpenAPI
- Qt 6.12.0 Reference Documentation

# Qt OpenAPI

The Qt OpenAPI module provides functionality for generating Qt HTTP clients using Qt Network RESTful APIs. The main module features are the Qt OpenAPI generator and pre-generated `OpenApiCommon` library.

The Qt OpenAPI generator is a plugin to the OpenAPI generator. It allows you to autogenerate Qt HTTP clients in C++ using Qt Network APIs such as QRestAccessManager.

Note: The Qt OpenAPI generator uses the OpenAPI 3.1.1 specification as its reference. This affects features such as operation parameters and nullable model properties.

Note: Qt OpenAPI in 6.12 is in Technology Preview, excluding its API from Qt's compatibility promises.

## Using the module

Installation of the following packages is necessary to use the Qt OpenAPI module:

- OpenAPI generator (version 7.18.0 or later is recommended).
- Maven plugin (version 3.0 or later is recommended).
- Java JDK (version 17 or later is recommended).

/note The code produced by the Qt OpenAPI generator can vary across versions, as it depends on the version of the upstream OpenAPI generator currently in use. Older generator versions might not support some of the features.

Once you have the required installations, the Qt OpenAPI generator is ready for use within your projects. To generate client code from an OpenAPI specification using the Qt OpenAPI Generator, call the qt_add_openapi_client function inside your project's CMakeLists.txt file. See Building with CMake for details.

### Building with CMake

#### Using the `qt_add_openapi_client` function

Use the `find_package()` command to locate the needed module components in the Qt6 package. Then call the qt_add_openapi_client function to generate a required Qt HTTP client library. See the full CMake code example below:

     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 Qt6::Core generatedLibrary)

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

Note: `OpenApiTools` library doesn't need to be linked to the resulting `openapiApplication` target. However, it's still required for enabling the qt_add_openapi_client cmake function.

Note: `OpenApiCommon` library is linked to the target by the qt_add_openapi_client call.

#### Calling the Qt OpenAPI Generator from the command line

To generate client code from an OpenAPI specification using the Qt OpenAPI Generator, you should run the following command:

     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

The command above adds the Qt OpenAPI generator to the classpath, which makes it visible to the upstream OpenAPI generator, then invokes main class `org.openapitools.codegen.OpenAPIGenerator`. Setting the Qt OpenAPI generator's name `cpp-qt6-client` to the `-g` parameter makes sure it will be found and called.

To generate client code from an extra large OpenAPI specification file, add the `maxYamlCodePoints` option to the command line, see below:

     java -DmaxYamlCodePoints=99999999 <other arguments>

Note: Always add `--additional-properties=cppCommonNamespace=QtOpenApiCommon,prefix=QOAI` if you want to link the pre-generated `Qt6::OpenApiCommon` library to the project, because it was built with these parameters, and you'll get compilation errors if you provide different values.

The generator creates the client library in the `generator_output` folder. Add the `generator_output` folder to the project, as shown in the following example:

     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)

If you want to see all generation options, you can use the `config-help` option, see below:

     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

Note: You can find more information about the generator usage in the OpenAPI generator documentation.

## Security Considerations

When using Qt OpenAPI, consider the following security-related aspects:

- Handling OpenAPI Specifications from External Sources
- Network communication

## Examples

- Qt OpenAPI Examples

## Reference

This module provides build tools (CMake commands) rather than a runtime C++ API. See CMake Commands in Qt6 OpenApi for the available commands.

## Licenses and Attributions

Different parts of the Qt OpenAPI module are available under different licenses.

The Qt OpenApiCommon library is available under commercial licenses from The Qt Company. In addition, it is available under the GNU Lesser General Public License, version 3, or the GNU General Public License, version 2. See Qt Licensing for further details.

The Qt OpenAPI Generator plugin, together with the template files for the code generation (that have the `.mustache` extension), are derived from the upstream OpenAPI generator project, and are licensed under the Apache License 2.0.