Cliente API RESTful de ColorPalette

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

Ejecución del ejemplo

Para ejecutar el ejemplo desde Qt Creatorabra el modo Welcome y seleccione el ejemplo de Examples. Para obtener más información, consulte Qt Creator: Tutorial: Construir y ejecutar.

Funcionalidad de la aplicación

El ejemplo proporciona las mismas funcionalidades básicas que Qt Quick Demo - RESTful API client.

Selección del servidor

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

• Ejemplo deservidor API REST basado en Qt en QtHttpServer

Una vez seleccionado el servidor y pulsado el botón Connect, el cliente API RESTful emite una petición HTTP GET de prueba para verificar que el servidor está disponible. Si el servidor no se está ejecutando, la aplicación permanece en la vista de selección de servidor.

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

El archivo CMakeLists.txt invoca al generador OpenAPI de Qt para generar código cliente a partir de la especificación colorpalette.yaml llamando a la función qt6_add_openapi_client.

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

Las clases API generadas ColorsApi y UsersApi manejan todos los detalles HTTP de bajo nivel:

• Configuración del servidor
• Construcción de peticiones 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
• El éxito y los errores se notifican a través de señales Qt

Comparado con la otra versión del ejemplo que utiliza las APIs QtNetworkAuth directamente, este enfoque elimina la construcción manual de peticiones de red.

Exposición de las API generadas a QML

Las clases API generadas ColorsApi y UsersApi se exponen a QML mediante clases helper definidas en ApiBridges.h. Cada helper utiliza la macro QML_FOREIGN y registra la instancia C++ subyacente como un singleton, lo que permite a QML acceder al mismo objeto mientras la propiedad permanece en C++. Para más detalles sobre este tema, consulte la documentación de Qt Qml sobre la exposición de un objeto existente como 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 globalmente en QML. Esto permite a los componentes QML acceder directamente a ColorsApi y UsersApi y llamar a sus métodos, como se muestra a continuación:

ColorsApi.getColors(page)

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

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

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

Tipos helpper singleton

Algunos métodos de la API toman como parámetros tipos no triviales, como Credentials y Color. El ejemplo proporciona singletons 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 en QML al llamar a los 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 @ code.qt.io