Aufgabe 16 - OpenAPI schreiben und Client generieren

Aufgabe 16 - OpenAPI schreiben und Client generieren

Worum geht es?

Sie schreiben die Endpunktliste aus Aufgabe 15 als OpenAPI-Beschreibung und erzeugen daraus einen Client (siehe Kapitel Schnittstellen im Vergleich). Damit haben Sie den Vertragsgedanken aus der SOAP-Welt in Ihrem eigenen Projekt, und Sie sehen an einem einzigen Befehl, was eine maschinenlesbare Beschreibung wert ist.

Was Sie dafür brauchen

• Kapitel Schnittstellen im Vergleich, Abschnitt Vertrag zuerst oder Code zuerst.
• Die Endpunkttabelle aus Aufgabe 15.
• Einen Editor mit OpenAPI-Unterstützung und einen Generator, etwa openapi-typescript oder Swagger Editor. Ihre Lehrkraft nennt Ihnen die Werkzeuge der Klasse.

Welche Kompetenzen Sie erwerben und zeigen

• Sie beschreiben eine Schnittstelle in OpenAPI mit Pfaden, Parametern, Antworten und Schemata.
• Sie erzeugen aus der Beschreibung einen typisierten Client und eine Dokumentationsseite.
• Sie begründen die Paradigmenwahl für Ihr Projekt und benennen die verworfene Alternative.

Pädagogische Einordnung

• Reproduktion: eine vorgegebene Beschreibung lesen und ergänzen (Teil A).
• Reorganisation und Transfer: die eigene Endpunktliste in OpenAPI überführen (Teil B).
• Reflexion, Problemlösung und Urteilsbildung: aus dem Vertrag generieren und die Paradigmenwahl begründen (Teil C).

Arbeitsaufträge

Die Übung ist auf etwa zwei Stunden ausgelegt.

Teil A - Eine vorhandene Beschreibung lesen

1. Kopieren Sie die OpenAPI-Beschreibung aus dem Kapitel in eine Datei openapi.yaml und öffnen Sie sie im Editor.

2. Beantworten Sie fünf Fragen allein anhand der Datei, jeweils mit der Zeilennummer als Beleg: Welchen Pfad gibt es? Welche Parameter nimmt er entgegen und welche davon sind verpflichtend? Welche Statuscodes sind beschrieben? Welche Felder hat ein Booking? Und welche davon sind Pflicht?

3. Ergänzen Sie die Beschreibung um einen zweiten Pfad /machines, der eine Liste von Maschinen liefert. Eine Maschine hat mindestens id und name. Prüfen Sie danach im Editor, ob die Datei gültig ist.

4. Ergänzen Sie beim bestehenden Pfad die Antwort 401 mit einer Beschreibung.

5. Bauen Sie absichtlich einen Fehler ein, etwa einen falsch eingerückten Schlüssel oder einen Verweis auf ein Schema, das es nicht gibt. Notieren Sie die Meldung des Editors und beheben Sie den Fehler. Sie werden diese Meldung in Teil B wiedersehen.

Teil B - Die eigene Schnittstelle beschreiben

1. Legen Sie openapi.yaml im Repository an, mit info, Titel und Version.

2. Übertragen Sie Ihre Endpunkttabelle aus Aufgabe 15 in die Datei. Jeder Pfad bekommt seine Methoden, jede Methode ihre Parameter und ihre Antworten mit den festgelegten Statuscodes.

3. Beschreiben Sie unter components/schemas die drei bis fünf wichtigsten Ressourcen Ihres Projekts. Zu jedem Schema gehören die Felder mit Typ und die Liste der Pflichtfelder.

4. Setzen Sie Ihre Festlegungen aus Aufgabe 15 in der Beschreibung um: Datumsfelder mit format: date-time, lange IDs als type: string, Aufzählungen als enum.

5. Prüfen Sie die Datei auf Gültigkeit und beheben Sie alle Meldungen.

6. Erzeugen Sie die Dokumentationsseite aus Ihrer Beschreibung und sehen Sie sie im Browser an. Notieren Sie zwei Stellen, an denen die Ansicht Ihnen einen Fehler oder eine Lücke gezeigt hat, die Sie in der YAML-Datei übersehen hatten.

7. Committen Sie openapi.yaml. Sie wird ab jetzt mitgepflegt, und in Kapitel 7 kommt die Prüfung dazu, die im Build feststellt, ob die Implementierung noch dazu passt.

Teil C - Generieren und begründen

1. Erzeugen Sie aus Ihrer Beschreibung einen typisierten Client, etwa mit openapi-typescript. Notieren Sie den Befehl und den Namen der erzeugten Datei.

2. Schreiben Sie ein kurzes Programm, das den Client verwendet, um einen Ihrer Endpunkte aufzurufen. Der Server existiert noch nicht, das ist in Ordnung: Der Aufruf darf fehlschlagen.

3. Provozieren Sie einen Typfehler. Übergeben Sie einem Feld einen falschen Typ, etwa eine Zahl, wo eine Zeichenkette erwartet wird. Notieren Sie die Meldung, die Sie bekommen, und in zwei Sätzen, an welcher Stelle Sie sie bekommen: beim Schreiben, beim Übersetzen oder erst zur Laufzeit.

4. Ändern Sie in openapi.yaml ein Pflichtfeld, etwa indem Sie es umbenennen. Erzeugen Sie den Client neu und notieren Sie, was jetzt passiert. Beschreiben Sie in drei bis vier Sätzen, warum das genau der Effekt ist, den man von einem Vertrag erwartet. Machen Sie die Änderung danach rückgängig.

5. Erklären Sie in vier bis fünf Sätzen den Unterschied zwischen „Vertrag zuerst” und „Code zuerst”. Beschreiben Sie dabei die Situation aus dem Kapitel, in der eine Seite auf die andere wartet, und wie ein Mock aus der Beschreibung das auflöst.

6. Schreiben Sie den Eintrag ins Entscheidungsprotokoll docs/entscheidungen.md, mit den vier Abschnitten Entscheidung, Alternativen, Begründung und Folgen. Die Entscheidung lautet, welches Paradigma Ihre Schnittstelle verwendet. Als Alternativen gehören mindestens zwei der drei anderen aus dem Kapitel hinein, jeweils mit ihrem stärksten Vorzug und dem Grund, warum es dieser Vorzug bei Ihnen nicht aufwiegt.

7. Beurteilen Sie zum Schluss in drei bis vier Sätzen, was Sie an Ihrer Endpunktliste geändert haben, seit Sie versucht haben, sie formal aufzuschreiben. Wer nichts geändert hat, sieht noch einmal nach.

Wissenscheck

1. Was beschreibt eine OpenAPI-Datei, und was lässt sich daraus erzeugen?
2. Worin unterscheidet sich OpenAPI von einer WSDL?
3. Was heißt „Vertrag zuerst”, und in welcher Situation zahlt es sich am deutlichsten aus?
4. Warum ist eine Beschreibung, die nicht zur Implementierung passt, schlechter als gar keine?
5. Warum bekommt ein Feld mit Datum und Zeit format: date-time statt einfach type: string?
6. Wozu dient die Liste der Pflichtfelder in einem Schema?
7. Nennen Sie zwei Vorteile, die ein generierter Client gegenüber selbst geschriebenen Aufrufen hat.

Abgabe

openapi.yaml liegt vollständig im Repository und beschreibt alle Endpunkte aus Aufgabe 15 samt Schemata. Der generierte Client und das kleine Testprogramm liegen daneben. Der Eintrag zur Paradigmenwahl steht in docs/entscheidungen.md. In protokoll.md stehen die Antworten aus Teil A, die zwei Befunde aus der Dokumentationsansicht und die Beobachtungen aus dem Vertragsbruch in Teil C.