ColorPalette RESTful-API-Client

Dieses Beispiel zeigt, wie man mit dem Qt OpenAPI-Generator RESTful-API-Client-Code aus der „ colorpalette.yaml “-Spezifikation erstellt und in eine QML-Anwendung integriert. Die Struktur und die Benutzeroberfläche entsprechen weitgehend dem Beispiel „Qt Quick -Demo – RESTful-API-Client“, sodass die Unterschiede hinsichtlich des Netzwerk- und Integrationsansatzes leicht zu erkennen sind.

Ausführen des Beispiels

Sie können das Beispiel wie folgt ausführen:

• Qt Creator

  Öffnen Sie den Modus „ Welcome “ und wählen Sie das Beispiel unter „ Examples “ aus. Weitere Informationen finden Sie unter Qt Creator: Tutorial: Erstellen und Ausführen.

• Qt Extension for Visual Studio Code

  Führen Sie den Befehl „ Qt: Open Qt examples “ über „ Command Palette “ aus und wählen Sie das Beispiel aus der Liste aus. Weitere Informationen finden Sie unter Qt Extension for Visual Studio Code: Tutorial: Erstellen und Ausführen.

Funktionalität der Anwendung

Das Beispiel bietet dieselben Grundfunktionen wie die „Qt Quick -Demo – RESTful-API-Client“.

Serverauswahl

Beim Start zeigt die Anwendung eine vordefinierte Serveroption an, mit der der „Color Palette“-Client kommunizieren kann:

• Beispiel für einen Qt-basierten REST-API-Server in QtHttpServer

Sobald der Server ausgewählt und die Schaltfläche „ Connect “ gedrückt wurde, sendet 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.

Generieren von Client-Code aus einer OpenAPI-Spezifikation

Die Datei „ CMakeLists.txt “ ruft den Qt-OpenAPI-Generator auf, um anhand der „ colorpalette.yaml “-Spezifikation Client-Code zu generieren, indem die Funktion „qt_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 “ übernehmen alle low-level HTTP-Details:

• Serverkonfiguration
• Erstellung von HTTP-Anfragen für alle Standard-HTTP-Methoden
• Serialisierung der Eingabeparameter gemäß der Spezifikation
• Deserialisierung von Serverantworten in typisierte Objekte
• Erfolge und Fehler werden über Qt-Signale gemeldet

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

Bereitstellung der generierten APIs für QML

Die generierten API-Klassen „ ColorsApi “ und „ UsersApi “ werden über Hilfsklassen, die in „ ApiBridges.h “ definiert sind, für QML bereitgestellt. Jede Hilfsklasse verwendet das Makro „ QML_FOREIGN “ und registriert die zugrunde liegende C++-Instanz als Singleton, wodurch QML auf dasselbe Objekt zugreifen kann, während die Eigentumsrechte bei C++ verbleiben. Weitere Details zu diesem Thema finden Sie in der Qt Qml-Dokumentation zum Bereitstellen eines bestehenden Objekts als Singleton.

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

};

Verwendung der APIs aus QML

Nach der Registrierung stehen die APIs in QML global zur Verfügung. Dadurch können QML-Komponenten direkt auf ColorsApi und UsersApi zugreifen und deren Methoden aufrufen, wie unten gezeigt:

ColorsApi.getColors(page)

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

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

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

Hilfs-Singleton-Typen

Einige API-Methoden nehmen nicht-triviale Typen als Parameter entgegen, wie beispielsweise „ Credentials “ und „ Color “. Das Beispiel stellt QML-Singletons bereit, um Instanzen solcher Typen in „ ApiBridges.h “ zu erstellen:

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. Beispielsweise wird ` Credentials ` verwendet, um vor der Anmeldung ein Anmeldeobjekt zu erstellen:

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

Quelldateien

Beispielprojekt auf code.qt.io