En esta página

qt_add_openapi_client

Genera un cliente HTTP utilizando una especificación OpenAPI proporcionada.

El comando está definido en el componente « OpenApiTools » del paquete « Qt6 ». Carga el paquete con:

find_package(Qt6 REQUIRED COMPONENTS OpenApiTools)

Este comando se introdujo en Qt 6.11.

Nota: Este comando se encuentra en fase de vista previa tecnológica y puede sufrir cambios en futuras versiones.

Sinopsis

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

Si los comandos sin versión están desactivados, utiliza en su lugar qt6_add_openapi_client(). Admite el mismo conjunto de argumentos que este comando.

Descripción

La función ` qt_add_openapi_client ` invoca el generador Qt OpenAPI para un archivo de especificación proporcionado. Como resultado, el comando genera el conjunto de archivos fuente y los añade a la lista de fuentes del destino. Si el destino no existe, la generación se detendrá con un mensaje de error. Para crear el destino, puedes llamar a las funciones ` qt_add_library ` o ` qt_add_executable `.

Nota: Actualmentesolo se admite la generación de código « client ».

Argumentos

  • SPEC_FILE especifica un archivo de especificación OpenAPI, obligatorio para la generación de código. El archivo debe tener la extensión *.yaml.
  • OUTPUT_DIRECTORY especifica el directorio de salida para el código generado. Si no se especifica, se utiliza CMAKE_CURRENT_BINARY_DIR.
  • ADDITIONAL_PROPERTIES especifica propiedades de configuración adicionales para el comando «generate». Se pasan tal cual al OpenAPI Generator sin validación.
  • GENERATE_OPTIONS Especifica opciones adicionales que se pasan al comando «generate ».

    Se ignorarán los argumentos « -i » y « --input-spec » pasados a través de « GENERATE_OPTIONS ». El archivo de especificación OpenAPI se establece exclusivamente mediante el argumento « SPEC_FILE ».

    Se ignorarán los argumentos -o y --output pasados a través de GENERATE_OPTIONS. El directorio de salida se configura exclusivamente mediante el argumento OUTPUT_DIRECTORY.

  • JAVA_OPTIONS especifica opciones adicionales que se pasan a la JVM al invocar el generador de OpenAPI. Utilízalo para configurar el comportamiento de la JVM. Las opciones se pasan tal cual, sin validación.
  • GENERATE_DOCUMENTATION (desde Qt 6.12) habilita la generación de documentación doxygen para las clases generadas.
  • DOCUMENTATION_OUTPUT_DIRECTORY (desde Qt 6.12) especifica un directorio en el que se almacenará la documentación de doxygen. La opción solo se puede utilizar junto con GENERATE_DOCUMENTATION.
  • OUTPUT_PUBLIC_HEADERS_DIR Especifica un directorio en el que se almacenará la lista de encabezados públicos generados; de lo contrario, los encabezados se encontrarán en OUTPUT_DIRECTORY.
  • OUTPUT_PRIVATE_HEADERS_DIR Especifica un directorio en el que se almacenará la lista de encabezados privados generados; de lo contrario, los encabezados se encontrarán en OUTPUT_DIRECTORY.

Personalización del comportamiento de generación

Los argumentos GENERATE_OPTIONS y ADDITIONAL_PROPERTIES te permiten personalizar el comportamiento tanto del generador OpenAPI original como del complemento generador de Qt.

El ejemplo siguiente muestra cómo puedes utilizar ambos argumentos conjuntamente en tu proyecto:

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
)

El comportamiento y los valores admitidos de los argumentos del generador dependen de la versión instalada de OpenAPI Generator y pueden variar de una versión a otra.

Puedes proporcionar propiedades de configuración adicionales de dos maneras:

  • Utilizando el argumento ADDITIONAL_PROPERTIES.
  • Pasando « -p » o « --additional-properties » en el argumento « GENERATE_OPTIONS ».

Utilizar ambos simultáneamente puede dar lugar a resultados inesperados. Recomendamos elegir un único método.

Nota: Algunas propiedades adicionales tienen valores fijos que no se pueden sobrescribir. Si intentas sobrescribirlas, tus valores se ignorarán. Por ejemplo, la propiedad adicional packageName se corresponde con el parámetro <target> de la función y no se puede modificar.

Personalización del comportamiento de la JVM

El siguiente ejemplo muestra cómo aumentar el límite del analizador YAML para archivos de especificación de gran tamaño y reducir la salida de registro a solo advertencias utilizando JAVA_OPTIONS:

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

© 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.