Cliente de la API RESTful de ColorPalette
Ejemplo de cómo generar el código del cliente OpenAPI e integrarlo en una aplicació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:
- Qt Creator
Abre el modo « Welcome » y selecciona el ejemplo en Examples. Para obtener más información, consulta Qt Creator: Tutorial: Compilar y ejecutar.
- Qt Extension for Visual Studio Code
Ejecute el comando « Qt: Open Qt examples » desde Command Palette y seleccione el ejemplo de la lista. Para obtener más información, consulte Qt Extension for Visual Studio Code: Tutorial: Compilar y ejecutar.
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.

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