Client API RESTful ColorPalette

Cet exemple montre comment utiliser le générateur Qt OpenAPI pour créer un code client RESTful API à 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, de sorte que les différences dans l'approche de la mise en réseau et de l'intégration sont faciles à identifier.

Exécution de l'exemple

Pour exécuter l'exemple à partir de Qt Creatorouvrez le mode Welcome et sélectionnez l'exemple à partir de Examples. Pour plus d'informations, voir Qt Creator: Tutoriel : Construire et exécuter.

Fonctionnalité de l'application

L'exemple fournit les mêmes fonctionnalités de base que Qt Quick Demo - RESTful API client.

Sélection du serveur

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

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

Une fois le serveur sélectionné et le bouton Connect enfoncé, le client API RESTful émet 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 dans la vue de sélection du serveur.

Générer 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 qt6_add_openapi_client.

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

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

• Configuration du serveur
• Construction de 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 par 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 à 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 à partir de QML

Une fois enregistrées, les API sont disponibles globalement dans QML. Cela permet aux composants QML d'accéder directement à ColorsApi et UsersApi et d'appeler leurs méthodes, comme indiqué ci-dessous :

ColorsApi.getColors(page)

Chaque méthode API émet des signaux lorsque l'opération réussit 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 de l'API prennent des types non triviaux comme paramètres, tels que Credentials et Color. L'exemple fournit des singletons QML pour 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 des méthodes de l'API. Par exemple, Credentials est utilisé pour créer un objet "credentials" avant de se connecter :

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

Fichiers sources

Exemple de projet @ code.qt.io