En esta página

Cliente de la API RESTful de ColorPalette

Ejemplo de cómo generar el código del cliente OpenAPI e integrarlo en una aplicación.

Tabla de paleta de colores con muestras de color, nombres, valores hexadecimales RGB, valores Pantone y botones de acción

Este ejemplo muestra cómo utilizar el generador Qt OpenAPI para crear código de cliente de la API RESTful a partir de la especificación colorpalette.yaml e integrarlo en una aplicación QML. Su estructura y su interfaz de usuario se asemejan mucho al ejemplo «Qt Quick Demo - RESTful API client», de modo que las diferencias en el enfoque de red e integración resultan fáciles de identificar.

Ejecución del ejemplo

Puede ejecutar el ejemplo desde:

Funcionalidad de la aplicación

El ejemplo ofrece las mismas funcionalidades básicas que la demo deQt Quick: cliente de API RESTful.

Selección del servidor

Al iniciarse, la aplicación presenta una opción de servidor predefinida con la que el cliente de Color Palette puede comunicarse:

Una vez seleccionado el servidor y pulsado el botón « Connect », el cliente de la API RESTful envía una solicitud HTTP GET de prueba para comprobar que el servidor está disponible. Si el servidor no está en funcionamiento, la aplicación permanece en la pantalla de selección de servidor.

Cuadro de diálogo de selección de servidor con la opción de servidor API REST basado en Qt y el botón «Conectar»

Generación de código de cliente a partir de una especificación OpenAPI

El archivo « CMakeLists.txt » invoca el generador Qt OpenAPI para generar código de cliente a partir de la especificación colorpalette.yaml mediante la llamada a la función qt_add_openapi_client().

qt_add_openapi_client(ColorpaletteClientExample
    SPEC_FILE
        ${CMAKE_CURRENT_SOURCE_DIR}/colorpalette.yaml
)

Las clases de API generadas, ColorsApi y UsersApi, se encargan de todos los detalles HTTP de bajo nivel:

  • Configuración del servidor
  • Creación de solicitudes HTTP para todos los métodos HTTP estándar
  • Serialización de los parámetros de entrada según la especificación
  • Deserialización de las respuestas del servidor en objetos tipados
  • Los éxitos y los errores se notifican a través de señales de Qt

En comparación con la otra versión del ejemplo, que utiliza directamente las API de QtNetworkAuth, este enfoque elimina la necesidad de crear manualmente las solicitudes de red.

Exposición de las API generadas a QML

Las clases de API generadas ColorsApi y UsersApi se exponen a QML a través de clases auxiliares definidas en ApiBridges.h. Cada clase auxiliar utiliza la macro QML_FOREIGN y registra la instancia subyacente de C++ como un singleton, lo que permite a QML acceder al mismo objeto mientras la propiedad sigue recayendo en C++. Para obtener más detalles sobre este tema, consulta la documentación de Qt Qml sobre cómo exponer un objeto existente como un singleton.

struct ForeignColorsAPI
{
    Q_GADGET
    QML_FOREIGN(QtOpenAPI::ColorsApi)
    QML_SINGLETON
    QML_NAMED_ELEMENT(ColorsApi)

};

Uso de las API desde QML

Una vez registradas, las API están disponibles de forma global en QML. Esto permite a los componentes de QML acceder directamente a ColorsApi y UsersApi e invocar sus métodos, tal y como se muestra a continuación:

ColorsApi.getColors(page)

Cada método de la API emite señales cuando la operación se realiza con éxito o falla, lo que permite a los componentes de QML gestionar las respuestas del servidor:

function onAddColorFinished() {
    root.fetchColors(root.currentColorPage)
}

function onAddColorErrorOccurred(errorType, errorStr) {
    root.handleError(errorStr)
}
Tipos singleton auxiliares

Algunos métodos de la API admiten como parámetros tipos no triviales, como Credentials y Color. El ejemplo proporciona singletons de QML para construir instancias de dichos tipos en ApiBridges.h:

class Credentials: public QObject
{
    Q_OBJECT
    QML_ELEMENT
    QML_SINGLETON
public:
    Q_INVOKABLE QtOpenAPI::Credentials create(const QString &email, const QString &password)
    {
        QtOpenAPI::Credentials credentials;
        credentials.setEmail(email);
        credentials.setPassword(password);
        return credentials;
    }
};

Estos singletons pueden utilizarse posteriormente en QML al llamar a métodos de la API. Por ejemplo, Credentials se utiliza para crear un objeto de credenciales antes de iniciar sesión:

let credentials = Credentials.create(userInfo.model.email, "apassword");
UsersApi.loginUser(credentials);

Archivos fuente

Proyecto de ejemplo en code.qt.io

Véase también Todos los ejemplos de Qt, Demostración deQt Quick: cliente de API RESTful y Servidor de API RESTful.

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