Swagger-UI
Grundsätzliche Bedienung
Die grafische Oberfläche für die Service-Definition kann hier geöffnet werden.
Auswahl der gewünschten Version / Anwendungsbereiches
Die verschiedenen Versionen für den gewünschten Anwendungsbereich lassen sich über das Auswahlmenü im rechten oberen Bereich auswählen:
Grundsätzlich wird Versionierung nur über die Url unterstützt. Innerhalb eines Versionsbereiches pro Anwendungsbereich werden in der Regel non-breaking changes in der selben Versionsnummer veröffentlicht.
Dies würde also bspw. für eine zusätzliche Eigenschaft in einer Klasse oder auf einen zusätzlichen Endpunkt zutreffen, die üblicherweise keine Auswirkungen auf bestehende Funktionalitäten haben.
Davon abweichende Änderungen, wie im Verhalten geänderte Endpunkte / geänderte Datentypen in bestehenden Klasseneigenschaften und dergleichen würden in die nächst höhere Versionsnummer aufgenommen werden.
Code-Generierung durch Tools
Hierbei sollte darauf geachtet werden, dass bei der Erstellung der Zugriffsklassen ( DTO's ) wenn möglich echte Datumstypen ( in c# also bspw. System.DateTime ) für die zahlreichen Felder GiltAb / GiltBis / Referenzdatum / Änderungszeitpunkt usw. gewählt werden.
Authentifizierung / Authorisierung
Über den "Authorize" Button kann ein Dialogfenster geöffnet werden, über das sich die zuvor beim msw abgeholten Zugangsdaten eingeben lassen.
Beschreibungen der Endpunkte und Klassen
Der Schwerpunkt der Dokumentation wurde auf die Metadaten zu den einzelnen Endpunkten, den zugehörigen Parametern und der Rückgabetypen gelegt.
Auf eine zusätzliche gesonderte- und letztlich redundante - Auflistung wurde bisher aus Zeitmangel verzichtet.
Der manuelle Zugriff über die Swagger-UI und / oder das EInlesen der entsprechenden swagger.json-Definitionsdateien, die diese Metadaten ebenfalls enthalten, ist aus unserer Sicht ein guter Einstieg.
Unterhalb der jeweiligen Endpunkte werden zahlreiche Informationen angeboten:
Für die Rückgabe-Objekte werden häufig sinnvolle Beispieldaten (Examples) angeboten:
Immer verfügbar ist die jeweilige Schemadefinition, wobei häufig zu jeder Eigenschaft / Feld zusätzliche Hinweise aufgeführt sind:
Am unteren Ende jeder Definitionsseite finden sich alle verwendeten Schemata:
