ColorPalette RESTful API-Client

Dieses Beispiel zeigt, wie man den Qt OpenAPI-Generator verwendet, um RESTful API-Client-Code aus der colorpalette.yaml -Spezifikation zu erstellen und in eine QML-Anwendung zu integrieren. Die Struktur und die Benutzeroberfläche entsprechen weitgehend dem Beispiel Qt Quick Demo - RESTful API client, so dass die Unterschiede in der Vernetzung und im Integrationsansatz leicht zu erkennen sind.

Ausführen des Beispiels

Zum Ausführen des Beispiels von Qt Creatorzu starten, öffnen Sie den Modus Welcome und wählen Sie das Beispiel aus Examples. Weitere Informationen finden Sie unter Qt Creator: Tutorial: Erstellen und Ausführen.

Funktionalität der Anwendung

Das Beispiel bietet die gleichen grundlegenden Funktionen wie Qt Quick Demo - RESTful API client.

Server-Auswahl

Beim Start präsentiert die Anwendung eine vordefinierte Serveroption, mit der der Color Palette Client kommunizieren kann:

• Qt-basiertes REST-API-Serverbeispiel in QtHttpServer

Sobald der Server ausgewählt und die Schaltfläche Connect gedrückt wurde, stellt der RESTful-API-Client eine Test-HTTP-GET-Anfrage, um zu überprüfen, ob der Server verfügbar ist. Wenn der Server nicht läuft, bleibt die Anwendung in der Serverauswahlansicht.

Generierung von Client-Code aus einer OpenAPI-Spezifikation

Die Datei CMakeLists.txt ruft den Qt OpenAPI-Generator auf, um Client-Code aus der Spezifikation colorpalette.yaml zu erzeugen, indem die Funktion qt6_add_openapi_client aufgerufen wird.

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

Die generierten API-Klassen ColorsApi und UsersApi behandeln alle HTTP-Details auf niedriger Ebene:

• Server-Konfiguration
• Aufbau von HTTP-Anfragen für alle Standard-HTTP-Methoden
• Serialisierung der Eingabeparameter entsprechend der Spezifikation
• Deserialisierung von Serverantworten in typisierte Objekte
• Erfolg und Fehler werden durch Qt-Signale gemeldet

Im Vergleich zur anderen Version des Beispiels, die direkt die QtNetworkAuth-APIs verwendet, entfällt bei diesem Ansatz die manuelle Erstellung von Netzwerkanfragen.

Freigabe der generierten APIs für QML

Die generierten API-Klassen ColorsApi und UsersApi werden QML über Helper-Klassen, die in ApiBridges.h definiert sind, zur Verfügung gestellt. Jede Hilfsklasse verwendet das Makro QML_FOREIGN und registriert die zugrunde liegende C++-Instanz als Singleton, so dass QML auf dasselbe Objekt zugreifen kann, während die Eigentümerschaft in C++ verbleibt. Weitere Details zu diesem Thema finden Sie in der Qt QML-Dokumentation über das Freigeben eines bestehenden Objekts als Singleton.

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

};

Verwendung der APIs von QML

Sobald die APIs registriert sind, stehen sie global in QML zur Verfügung. Dies ermöglicht es QML-Komponenten, direkt auf ColorsApi und UsersApi zuzugreifen und ihre Methoden aufzurufen, wie unten gezeigt:

ColorsApi.getColors(page)

Jede API-Methode gibt Signale aus, wenn der Vorgang erfolgreich ist oder fehlschlägt, so dass QML-Komponenten die Serverantworten verarbeiten können:

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

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

Hilfssingleton-Typen

Einige API-Methoden nehmen nicht-triviale Typen als Parameter an, wie z.B. Credentials und Color. Das Beispiel bietet QML-Singletons, um Instanzen solcher Typen in ApiBridges.h zu konstruieren:

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;
    }
};

Diese Singletons können dann in QML beim Aufruf von API-Methoden verwendet werden. Zum Beispiel wird Credentials verwendet, um ein Credentials-Objekt vor der Anmeldung zu erstellen:

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

Quelldateien

Beispielprojekt @ code.qt.io