Client de l'API RESTful ColorPalette

Cet exemple montre comment utiliser le générateur Qt OpenAPI pour créer du code client d’API RESTful à partir de la spécification colorpalette.yaml et l’intégrer dans une application QML. Sa structure et son interface utilisateur correspondent étroitement à l’exemple « Qt Quick Demo - RESTful API client », ce qui permet d’identifier facilement les différences au niveau de la mise en réseau et de l’approche d’intégration.

Exécution de l’exemple

Vous pouvez exécuter l’exemple à partir de :

• Qt Creator

  Ouvrez le mode « Welcome » et sélectionnez l’exemple dans « Examples ». Pour plus d’informations, consultez Qt Creator: Tutoriel : Compiler et exécuter.

• Qt Extension for Visual Studio Code

  Exécutez la commande « Qt: Open Qt examples » à partir de Command Palette, puis sélectionnez l’exemple dans la liste. Pour plus d’informations, consultez Qt Extension for Visual Studio Code: Tutoriel : Compiler et exécuter.

Fonctionnalités de l’application

Cet exemple offre les mêmes fonctionnalités de base que la démo «Qt Quick » - Client API RESTful.

Sélection du serveur

Au démarrage, l’application propose une option de serveur prédéfinie avec laquelle le client Color Palette peut communiquer :

• Exemple de serveur API REST basé sur Qt dans QtHttpServer

Une fois le serveur sélectionné et le bouton « Connect » (Générer le code client) cliqué, le client API RESTful envoie une requête HTTP GET de test pour vérifier que le serveur est disponible. Si le serveur n’est pas en cours d’exécution, l’application reste sur la vue de sélection du serveur.

Génération du code client à partir d’une spécification OpenAPI

Le fichier « CMakeLists.txt » invoque le générateur Qt OpenAPI pour générer du code client à partir de la spécification colorpalette.yaml en appelant la fonction qt_add_openapi_client().

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

Les classes API générées ColorsApi et UsersApi gèrent tous les détails HTTP de bas niveau :

• Configuration du serveur
• Construction des requêtes HTTP pour toutes les méthodes HTTP standard
• Sérialisation des paramètres d’entrée conformément à la spécification
• Désérialisation des réponses du serveur en objets typés
• Les succès et les erreurs sont signalés via des signaux Qt

Par rapport à l'autre version de l'exemple qui utilise directement les API QtNetworkAuth, cette approche élimine la construction manuelle des requêtes réseau.

Exposition des API générées vers QML

Les classes d'API générées ColorsApi et UsersApi sont exposées à QML via des classes d'aide définies dans ApiBridges.h. Chaque classe d'aide utilise la macro QML_FOREIGN et enregistre l'instance C++ sous-jacente en tant que singleton, ce qui permet à QML d'accéder au même objet tout en conservant la propriété en C++. Pour plus de détails sur ce sujet, consultez la documentation Qt Qml sur l'exposition d'un objet existant en tant que singleton.

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

};

Utilisation des API depuis QML

Une fois enregistrées, les API sont disponibles de manière globale dans QML. Cela permet aux composants QML d’accéder directement à ColorsApi et UsersApi et d’appeler leurs méthodes, comme illustré ci-dessous :

ColorsApi.getColors(page)

Chaque méthode d’API émet des signaux lorsque l’opération aboutit ou échoue, ce qui permet aux composants QML de gérer les réponses du serveur :

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

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

Types singleton d’aide

Certaines méthodes d’API prennent des types non triviaux en paramètres, tels que ` Credentials ` et ` Color`. L’exemple fournit des singletons QML permettant de construire des instances de ces types dans ` 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;
    }
};

Ces singletons peuvent ensuite être utilisés en QML lors de l’appel de méthodes de l’API. Par exemple, ` Credentials ` est utilisé pour créer un objet d’identifiants avant la connexion :

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

Fichiers source

Projet d’exemple sur code.qt.io