From 4fecc023d6a0cc52e403a199a07121407478d76c Mon Sep 17 00:00:00 2001 From: Falk Sippach Date: Thu, 21 Nov 2024 00:13:05 +0100 Subject: [PATCH] #10 initial version of chapter 5 --- docs/05-openapi/00-structure.adoc | 4 +-- docs/05-openapi/01-duration-terms.adoc | 14 ++------- docs/05-openapi/02-learning-goals.adoc | 40 +++++++++++++++----------- docs/05-openapi/references.adoc | 11 ------- 4 files changed, 28 insertions(+), 41 deletions(-) diff --git a/docs/05-openapi/00-structure.adoc b/docs/05-openapi/00-structure.adoc index 9a32fdf..d0e3d41 100644 --- a/docs/05-openapi/00-structure.adoc +++ b/docs/05-openapi/00-structure.adoc @@ -3,11 +3,11 @@ // ==================================================== // tag::DE[] -== Und so heißt Modul 5 +== Beschreibung von APIs am Beispiel OpenAPI // end::DE[] // tag::EN[] -== And This is Module no 5 +== Description of APIs using the example of OpenAPI // end::EN[] include::01-duration-terms.adoc[{include_configuration}] diff --git a/docs/05-openapi/01-duration-terms.adoc b/docs/05-openapi/01-duration-terms.adoc index d1bb5f8..a8f56ff 100644 --- a/docs/05-openapi/01-duration-terms.adoc +++ b/docs/05-openapi/01-duration-terms.adoc @@ -1,6 +1,6 @@ // tag::DE[] |=== -| Dauer: XXX Min. | Übungszeit: XXX Min. +| Dauer: 90 Min. | Übungszeit: 30 Min. |=== === Begriffe und Konzepte @@ -10,20 +10,10 @@ Begriff 1, Begriff 2, Begriff 3 // tag::EN[] |=== -| Duration: XXX min | Practice time: XXX min +| Duration: 90 min | Practice time: 30 min |=== === Terms and Principles Term 1, Term 2, Term 3 // end::EN[] - -[NOTE] -==== -Überschrift in 00-structure.adoc ersetzen -==== - -[NOTE] -==== -Sinnvolle Zeiten für Dauer und Übungszeit eintragen, vernünftige Begriffe aufzählen. -==== diff --git a/docs/05-openapi/02-learning-goals.adoc b/docs/05-openapi/02-learning-goals.adoc index 026e525..1723b76 100644 --- a/docs/05-openapi/02-learning-goals.adoc +++ b/docs/05-openapi/02-learning-goals.adoc @@ -1,21 +1,34 @@ === {learning-goals} - // tag::DE[] [[LZ-5-1]] -==== LZ 5-1: Dies ist das erste Lernziel in Kapitel 5, lorem ipsum sit dolor - -Hier wird beschrieben, was Teilnehmer:innen in diesem Lernziel lernen sollen. Das kann in Prosa-Text -in ganzen Sätzen oder in Aufzählungen mit Unterpunkten erfolgen. Dabei kann auch unterschieden werden, -wie wichtig einzelne Aspekte des Lernziels sind. Es kann hier bereits auf Literatur verwiesen werden. +==== LZ 5-1: Wichtigkeit von API Beschreibungen kennen -* Erstes Teilziel -* Zweites Unterthema -* Dritter Aspekt +Teilnehmer:innen verstehen den Nutzen von API-Beschreibungen und kennen die Zielgruppen. Das Problem des "API Drift" ist bekannt. Sie können das Zusammenspiel von Design, Implementierung, Versionierung, Beschreibung, Versionierung der Beschreibung einordnen und wie diese Dinge im Idealfall sowie in der Realität praktiziert werden. [[LZ-5-2]] -==== LZ 5-2: Hier ist ein zweites Lernziel in diesem Kapitel -tbd. +==== LZ 5-2: OpenAPI als Beschreibungssprache für HTTP APIs einordnen + +Teilnehmer:innen verstehen OpenAPI als eine auf HTTP APIs spezialisierte Beschreibungssprache. +Sie kennen die Geschichte von OpenAPI und wie sich die verschiedenen Versionen entwickelt haben. +Teilnehmer:innen wissen, wie sich OpenAPI zur Codegenerierung auf der Anbieter- oder Konsumentenseite verwenden lässt. +Die generellen Strukturen von JSON und YAML sind bekannt. + +[[LZ-5-3]] +==== LZ 5-3: Der Aufbau von OpenAPI verstehen + +Teilnehmer:innen verstehen die Hauptelemente einer OpenAPI Beschreibung und wie diese für konkrete APIs verwendet werden. + +* Resourcen (Paths) +* Interaktionen +* Repräsentationen +* Mechanismen wie Tags, Security, Components und Webhooks + +[[LZ-5-4]] +==== LZ 5-4: Alternative Beschreibungssprachen kennen + +OpenAPI ist spezialisiert auf HTTP APIs. Für andere API-Stile können alternative Beschreibungssprachen mit ähnlichen generellen Zielen verwendet werden. Teilnehmer:innen kennen diese alternativen Beschreibungssprachen und können sie API-Stilen zuordnen. + // end::DE[] // tag::EN[] @@ -27,8 +40,3 @@ tbd. ==== LG 5-2: TBD tbd. // end::EN[] - -[NOTE] -==== -Die einzelnen Lernziele müssen nicht als einfache Aufzählungen mit Unterpunkten aufgeführt werden, sondern können auch gerne in ganzen Sätzen formuliert werden, welche die einzelnen Punkte (sofern möglich) integrieren. -==== diff --git a/docs/05-openapi/references.adoc b/docs/05-openapi/references.adoc index 459da49..6c93627 100644 --- a/docs/05-openapi/references.adoc +++ b/docs/05-openapi/references.adoc @@ -1,16 +1,5 @@ === {references} -<> - -[NOTE] -==== -Eine Quelle wird über `\<