Skip to Content

Changes for page Basisprojekt

Last modified by mgrawunder on 2025/09/09 08:42
From version arrow_back 37.3 arrow_forward
edited by mgrawunder
on 2025/09/03 10:02
Change comment: There is no comment for this version
To version arrow_back 39.1 arrow_forward
edited by mgrawunder
on 2025/09/03 11:01
Change comment: There is no comment for this version

Summary

Details

insert_drive_file Page properties
Content
... ... @@ -139,4 +139,155 @@
139 139  Dort wird die Datei auch grafisch dargestellt.
140 140  
141 141  
142 += Maven und OpenAPI =
143 +
144 +Die OpenAPI Datei kann verwendet werden, um sich die [[REST-Schnittstellen>>doc:||anchor="HErweiterungderREST-Schnittstelle"]] generieren  zu lassen. Diese Erzeugung erfolgt mit dem OpenAPI Generator [[https:~~/~~/github.com/OpenAPITools/openapi-generator>>https://github.com/OpenAPITools/openapi-generator]]
145 +
146 +Man kann dabei jetzt einen Kommandozeilenaufruf verwenden oder man setzt auf das im Basisprojekt vorhandene MVN ()
147 +
148 +Dafür ist in den Maven-Dateien bereits das OpenAPI Generator Plugin integriert. Da im Client und im Server unterschiedliche Arten verwendet werden, erfolgt die Konfiguration im Client und im Server unterschiedlich:
149 +
150 +== Client ==
151 +
152 +Im Client werden die Apache Http Bibliothek verwendet.
153 +
154 +
155 +[[image:1756887005209-855.png]]
156 +
157 +== Server ==
158 +
159 +Im Server wird Spring (Boot) verwendet
160 +
161 +[[image:1756887037619-847.png]]
162 +
163 +TODO: Weitere Informationen zu
164 +
165 +- Lombok
166 +
167 +- Dependency Injection
168 +
169 +- Spring (Boot), siehe auch [[https:~~/~~/www.marcobehler.com/guides/spring-framework>>https://www.marcobehler.com/guides/spring-framework]]
170 +
171 +
172 +
173 += Erweiterung der REST-Schnittstelle =
174 +
175 +In diesem Beispiel wird einmal gezeigt, wie die REST-Schnittstelle des Basisprojektes einfach erweitert werden kann.
176 +
177 +In diesem Beispiel soll die aktuelle Schnittstelle um die Möglichkeit erweitert werden, alle Lobbies vom Server zu bekommen.
178 +
179 +== Schritt 1: Erweitere das OpenAPI-Dokument ==
180 +
181 +Um diese neue Funktion sowohl im Client als auch im Server verwenden zu können, ist es notwendig, diese neue Funktion im OpenAPI-Dokument zu definieren.
182 +
183 +Die Funktion soll sehr einfach sein und keine Parameter verlangen. Dafür bietet sich die GET-Funktion an.
184 +
185 +Im folgenden Bild sind alle Anpassungen zu sehen:
186 +
187 +[[image:1756887436525-790.png||height="355" width="974"]]
188 +
189 +
190 +Nach dem Speichern, sollte das OpenAPI-Dokument wie folgt aussehen
191 +
192 +[[image:1756887488020-376.png||height="642" width="904"]]
193 +
194 +
195 +Jetzt kann man entweder in IntelliJ
196 +
197 +[[image:1756888245896-845.png||height="347" width="620"]]
198 +
199 +oder im Terminal (z.B. auch in IntelliJ)
200 +
201 +[[image:1756888279902-777.png||height="637" width="1053"]]
202 +
203 +Wobei hier auch clean compile reichen würde.
204 +
205 +**ACHTUNG! Falls maven Problem macht, kann das auch an einer falschen Java-Version im System liegen (siehe auch [[FAQ>>doc:.Basisprojekt FAQ.WebHome]])**
206 +
207 +Es werden durch den Aufruf neue Inhalte generiert (bzw. die alten überschrieben).
208 +
209 +[[image:1756888428042-802.png||height="538" width="1077"]]
210 +
211 +Hinweis: Niemals Änderungen unterhalb des target-Ordners machen. Das wird von Maven bei clean gelöscht.
212 +
213 +=== Wie bekommt man dann aber nun die Funktionalität rein? ===
214 +
215 +Für jeden Endpunkt (also aktuell lobbies und users) werden drei Interfaces/Klassen erzeugt:
216 +
217 +* *Api (z.B, LobbiesApi): Beschreibung der REST-Methoden, vor allem auch das Mapping von z.B. /lobbies/join auf die Methode lobbyJoin(String)
218 +* (((
219 +*ApiController implements *Api (Für Spring) (z.B. LobbiesApiController)
220 +)))
221 +* (((
222 +*ApiDelegate (z.B. LobbiesApiDelegate): Macht die eigentliche Arbeit und muss** im eigenen Code-Bereich** erweitert werden!
223 +)))
224 +
225 +
226 +
227 +== Schritt 2: Erweiterung auf Server-Seite ==
228 +
229 +Da es schon Funktionen für die Lobbies gibt, gibt es auch bereits eine Implementierung, die LobbiesApiDelegate überschreibt
230 +
231 +[[image:1756888762381-912.png||height="48" width="789"]]
232 +
233 +Wenn man einen neuen Endpunkt definiert, muss man auch einen neuen Service definieren. (Hinweis: Der Service muss eine Spring Komponenten sein, damit sie in den Spring Context aufgenommen wird).
234 +
235 +In der Klasse muss man dann die neue Methode lobbyList aus der API überschreiben.
236 +
237 +[[image:1756888929507-312.png||height="156" width="1161"]]
238 +
239 +Dabei wird folgendes gemacht:
240 +
241 +1. Es wird ein Rückgabeobjekt vom Typ Liste erzeugt
242 +1. Es wird über alles Lobbies auf dem Server gegangen (lobbyManagement.getLobbies())
243 +1. Da der Client u.U. nicht die vollständigen Informationen über die Lobbies bekommen soll, gibt es zwei unterschiedliche Klassen: ServerLobby und LobbyDTO.
244 +1. Die Foreach-Schleife sorgt dafür, dass in das Rückgabeobjekt nur die LobbyDTOs eingefügt werden.
245 +1. Dafür wird eine Funktion mit dem Namen lobbyMapping verwendet
246 +1. Schließlich wird am Ende gesagt, dass alles ok ist und eine Antwort ResponseEntity.ok mit dem Rückgabeobjekt (lobbies) gesendet.
247 +
248 +**Anmerkung**: Das Basisprojekt ist aktuell so eingerichtet, dass Spring Exceptions auffängt und entsprechend an den Client leitet. Diese findet in der Klasse  GlobalExceptionHandler statt
249 +
250 +Auf Server-Seite fehlt jetzt noch die Methode getLobbies im LobbyManagement
251 +
252 +[[image:1756889590500-656.png||height="81" width="518"]]
253 +
254 +
255 +=== LobbyMapping ===
256 +
257 +Da man relativ oft Server-Objekt in DTO umwandeln muss gibt es im Basisprojekt MapStruct. Damit muss man nur die DTO-Klasse anlegen (i.d.R. über OpenAPI!!)
258 +
259 +Also z.B.
260 +
261 +[[image:1756889440395-856.png]]
262 +
263 +und definiert ein Interface mit einer Annotation
264 +
265 +[[image:1756889472103-847.png]]
266 +
267 +und damit kann man die Funktion aufrufen. Hinweis: Der Mapper ist im LobbyService über die Spring Dependency Injection gebunden.
268 +
269 +== Schritt 3: Erweiterung auf Client-Seite (Java) ==
270 +
271 +Hinweis: Das Beispiel bezieht sich hier auf eine Client mit Java. Für andere Clients wie Angular ist das Vorgehen anders.
272 +
273 +Auf der Client-Seite wird die komplette Kommunikation mit dem Server in der generierten Klasse DefaultApi gekapselt.
274 +
275 +[[image:1756889795622-530.png]]
276 +
277 +Dort gibt es eine neue Methode lobbyList. Die sorgt dafür, dass der REST-Aufruf auf die Server-Seite geht und liefert das passende Objekt List<LobbyDTO> zurück
278 +
279 +Im Client gibt es auch eine Klasse LobbyService. Dort ist die DefaultApi Klasse über Dependency Injection gebunden.
280 +
281 +[[image:1756889917681-650.png]]
282 +
283 +Dort kann man nun eine neue Methode getLobbies() integrieren:
284 +
285 +[[image:1756889979252-910.png]]
286 +
287 +Und das Ganze dann z.B. im MainMenuPresenter verwenden:
288 +
289 +[[image:1756890010118-149.png||height="116" width="972"]]
290 +
291 +Anmerkung: Obwohl DefaultApi alle Funktionen zum Server kapselt, sollte man im Client spezifische Services für bestimmte Bereich haben, die diese Klasse verwenden.  Das führt zu einer besseren Trennung von Funktionalitäten im Code.
292 +
142 142  
attach_file 1756887005209-855.png
Author
... ... @@ -1,0 +1,1 @@
1 +XWiki.mgrawunder
Size
... ... @@ -1,0 +1,1 @@
1 +56.9 KB
Content info
attach_file 1756887037619-847.png
Author
... ... @@ -1,0 +1,1 @@
1 +XWiki.mgrawunder
Size
... ... @@ -1,0 +1,1 @@
1 +52.5 KB
Content info
attach_file 1756887436525-790.png
Author
... ... @@ -1,0 +1,1 @@
1 +XWiki.mgrawunder
Size
... ... @@ -1,0 +1,1 @@
1 +62.8 KB
Content info
attach_file 1756887488020-376.png
Author
... ... @@ -1,0 +1,1 @@
1 +XWiki.mgrawunder
Size
... ... @@ -1,0 +1,1 @@
1 +187.5 KB
Content info
attach_file 1756888245896-845.png
Author
... ... @@ -1,0 +1,1 @@
1 +XWiki.mgrawunder
Size
... ... @@ -1,0 +1,1 @@
1 +115.6 KB
Content info
attach_file 1756888279902-777.png
Author
... ... @@ -1,0 +1,1 @@
1 +XWiki.mgrawunder
Size
... ... @@ -1,0 +1,1 @@
1 +518.9 KB
Content info
attach_file 1756888428042-802.png
Author
... ... @@ -1,0 +1,1 @@
1 +XWiki.mgrawunder
Size
... ... @@ -1,0 +1,1 @@
1 +312.3 KB
Content info
attach_file 1756888762381-912.png
Author
... ... @@ -1,0 +1,1 @@
1 +XWiki.mgrawunder
Size
... ... @@ -1,0 +1,1 @@
1 +3.4 KB
Content info
attach_file 1756888929507-312.png
Author
... ... @@ -1,0 +1,1 @@
1 +XWiki.mgrawunder
Size
... ... @@ -1,0 +1,1 @@
1 +16.9 KB
Content info
attach_file 1756889440395-856.png
Author
... ... @@ -1,0 +1,1 @@
1 +XWiki.mgrawunder
Size
... ... @@ -1,0 +1,1 @@
1 +55.9 KB
Content info
attach_file 1756889472103-847.png
Author
... ... @@ -1,0 +1,1 @@
1 +XWiki.mgrawunder
Size
... ... @@ -1,0 +1,1 @@
1 +11.1 KB
Content info
attach_file 1756889590500-656.png
Author
... ... @@ -1,0 +1,1 @@
1 +XWiki.mgrawunder
Size
... ... @@ -1,0 +1,1 @@
1 +4.8 KB
Content info
attach_file 1756889795622-530.png
Author
... ... @@ -1,0 +1,1 @@
1 +XWiki.mgrawunder
Size
... ... @@ -1,0 +1,1 @@
1 +379.7 KB
Content info
attach_file 1756889917681-650.png
Author
... ... @@ -1,0 +1,1 @@
1 +XWiki.mgrawunder
Size
... ... @@ -1,0 +1,1 @@
1 +6.0 KB
Content info
attach_file 1756889979252-910.png
Author
... ... @@ -1,0 +1,1 @@
1 +XWiki.mgrawunder
Size
... ... @@ -1,0 +1,1 @@
1 +4.0 KB
Content info
attach_file 1756890010118-149.png
Author
... ... @@ -1,0 +1,1 @@
1 +XWiki.mgrawunder
Size
... ... @@ -1,0 +1,1 @@
1 +16.8 KB
Content info