Das Dokumentieren einer API wird oft als mühsame, aber wesentliche Aufgabe angesehen. Mit OpenAPI / Swagger können wir eine API-Dokumentation angenehm einfach in ASP.NET Core integrieren. Gregor Biswanger zeigt, wie eine API-Dokumentation mit einer Benutzeroberfläche hinzugefügt wird, mit der wir die API testen können. Als Nächstes erfahren wir, wie wir Attribute und Konventionen verwenden, um die generierte OpenAPI-Spezifikation zu verbessern. Abschließend wird gezeigt, wie wir mit der Authentifizierung, Versionierung und Anpassung der Benutzeroberfläche umgehen.

1. API-Dokumentation
mit OpenAPI/Swagger für ASP
.NET Core
Gregor Biswanger | Freier Berater, Trainer und Autor
about.me/gregor.biswanger

2. Dieser kostenlose Workshop ist ein Bestandteil meiner
kommerziellen Workshops zu:
▪ Einstieg in ASP
.NET Core (3-5 Tage)
▪ Advanced REST-APIs mit ASP
.NET Core (3 Tage)
▪ Einstieg in GraphQL mit ASP
.NET Core (3 Tage)
▪ Einstieg in gRPC mit ASP
.NET Core (2 Tage)
▪ Einstieg in SignalR mit ASP
.NET Core (2 Tage)
Lust das wir gemeinsam durchstarten bei deiner Firma?
Dann bitte einfach direkt an mich wenden!

3. Kostenlos auf meinem YouTube Kanal:
„.NET Web-API Entwicklung lernen“
http://bit.ly/dotnet-web-api-entwicklung

4. Über mich
▪ Freier Berater, Trainer und Autor
▪ Schwerpunkte: Softwarearchitektur, Web und
Cross-Plattform Entwicklung mit C# und JavaScript
▪ Papa von Electron.NET
▪ Technologieberater für die Intel Developer Zone
▪ Internationaler Sprecher auf Konferenzen und
User Groups
▪ Freier Autor für heise.de, dotnetpro,
WindowsDeveloper und viele weitere
Fachmagazine
▪ Video-Trainer bei video2brain und Microsoft
Gregor Biswanger
Microsoft MVP
, Intel Black Belt &
Intel Software Innovator
cross-platform-blog.de
about.me/gregor.biswanger

5. Reiseplan
▪ Einführung
▪ Setup und Start
▪ Meine erste API-Dokumentation
▪ Konventionen für die OpenAPI
▪ Umfangreiche Requests und Responses
▪ Versionierung
▪ Security
▪ Erweiterte Anpassung

6. Eine echte RESTfull API sollte immer den
Konsumenten mit seinen Möglichkeiten selbst
führen können.

7. Allerdings ist eine pragmatische HTTP-API
die am häufigsten zum Einsatz kommt.

8. Diese erfordern für ein besseres Verständnis,
einen Wegweiser mittels API-Dokumentation.

9. Ebenfalls ist eine API-Dokumentation für beide
varianten relevant um detaillierte Informationen
zu bieten.

10. Zum Beispiel: Security, Zugriffseinschränkungen
und weitere Sonderfälle.

11. Mithilfe der OpenAPI-Spezifikation können
wir unsere API Funktionen beschreiben.

12. Diese ist standardisiert und im
JSON- oder YAML-Format.

13. Swagger ist eine Sammlung von Open-Source-
Werkzeugen, um HTTP-Webservices zu entwerfen,
zu erstellen, zu dokumentieren und zu nutzen.

14. Swagger benutzt dazu den
Beschreibungsstandard OpenAPI.

15. OpenAPI-Komponenten und -Tools
REST API
Code
Web UI
API Tests
JSON
YAML
OpenAPI
Swagger Swagger

16. Swagger Open-Source Tools
Swagger Editor
Unterstützt beim
Erzeugen der API-
Definition.
Swagger Codegen
Generiert Server
Stubs und Client
SDKs
Swagger UI
Erzeugt
Dokumentation.

17. Daneben existieren auch kostenpflichtige Tools
▪ SwaggerHub für Kollaboration.
▪ SwaggerHub Enterprise für Unternehmen, verfügbar in der
Cloud oder On-Premises.
▪ Swagger Inspector für Testzwecke.
▪ APITree wandelt OpenAPI-Spezifikationen 2.0 und 3.0 in
menschenlesbare API-Dokumentationen um, die über einen HUB
kostenlos in der Cloud verwaltet und geteilt werden können.

18. Die Geschichte von Swagger / OpenAPI
2011 2015 2017
Swagger-API-Projekt
veröffentlicht
Linux-Foundation
Unterstützung
Mehr als 100.000
Downloads am Tag
Swagger-Spezifikation in OpenAPI
Spezifikation unbenannt

19. Swashbuckle.AspNetCore hilft bei der
Arbeit mit OpenAPI in ASP.NET Core

20. Swashbuckle.AspNetCore
Generiert eine
OpenAPI-Spezifikation
aus Ihrer API
Ein Wrapper für die
Swagger-UI und bietet
eine eingebettete
Version davon
NSwag ist eine
Alternative für
Swashbuckle

21. Setup und Start

22. Visual Studio 2019 und das .NET Core SDK
unter www.asp.net

23. Download der Vorlage
http://bit.ly/AspSwaggerWorkshop

24. C:dev>
Cloning into 'AspSwaggerWorkshop'...
remote: Enumerating objects: 111, done.
remote: Counting objects: 100% (111/111), done.
remote: Compressing objects: 100% (63/63), done.
Receiving objects: 39% (44/111) Total 111 (delta 52), reused 93 (delta 34), pack-reus
Receiving objects: 100% (111/111), 25.86 KiB | 3.69 MiB/s, done.
Resolving deltas: 100% (52/52), done.
C:dev>
git clone https://github.com/GregorBiswanger/AspSwaggerWorkshop.git
cd AspSwaggerWorkshop
C:devAspSwaggerWorkshop> dotnet restore
Wiederherzustellende Projekte werden ermittelt...
"C:UsersGregorsourcereposDevAspSwaggerWorkshopAspRestApiWorkshop.csproj" wied
C:dev>
Das Template mit
Git Clonen

25. C:devAspSwaggerWorkshop>
Das Tool "dotnet-ef" wurde in der neuesten Version installiert (Version 5.0.4).
C:devAspSwaggerWorkshop>
dotnet tool install --global dotnet-ef
Die Entity Framework CLI
installieren

26. C:devAspSwaggerWorkshop>
_/__
---==/
___ ___ |. |
| __|| __| | )
| _| | _| _/ | //|
|___||_| / /
Entity Framework Core .NET Command Line Tools 5.0.4
Usage: dotnet ef [options] [command]
Options:
--version Show version information
-h|--help Show help information
-v|--verbose Show verbose output.
--no-color Don't colorize output.
--prefix-output Prefix output with level.
Commands:
dotnet ef
Der Kommando dotnet ef
steht für die EF CLI

27. C:devAspSwaggerWorkshop>
Build started...
Build succeeded.
Done.
C:devAspSwaggerWorkshop>
dotnet ef database update
Der Migration-Code wird ausgeführt um
die Datenbank zu Erzeugen

28. Postman herunterladen und installieren
www.postman.com/downloads

29. Kestrel Web-Server
auswählen und starten

30. Meine erste App-Dokumentation

31. Unsere Ressourcen
Camp
Talk
Speaker
Location

32. API Design
http://.../api/camps
http://.../api/camps/DWX2020
http://.../api/camps/DWX2020/talks
http://.../api/camps/DWX2020/talks?topic=dotnet
http://.../api/camps/DWX2020/talks/1
http://.../api/camps/DWX2020/talks/1/speaker
http://.../api/reloadconfig

33. Swashbuckle
hinzufügen

34. Swashbuckle ist
bereits installiert

35. Swagger unter
Services registrieren

36. Die Swagger-Middleware
einbinden

37. Die automatisch erzeugte
OpenAPI JSON-Datei

38. Allgemeine Informationen
API-Routen + Meta-Daten
DTO´s + Meta-Daten

39. Swagger UI
hinzufügen

40. Die Swagger UI-
Middleware einbinden

41. Projekt ausführen und die
Swagger UI im Browser öffnen

42. API-Route öffnen und
zum Testen auswählen

43. API-Anfrage abschicken

44. Die Antwort wird direkt
darunter angezeigt

45. Benutzerdefinierte Route
für die Swagger UI festlegen

46. Swagger UI über die
neue URL öffnen

47. XML-Dokumentationskommentare
hinzufügen

48. XML-Dokumentationskommentar
hinzufügen

49. In die Eigenschaften wechseln,
mit einem Doppelklick auf
Properties.

50. XML-Dokumentationskommentare
für das Projekt aktivieren

51. Fester Pfad zur XML-
Datei entfernen

52. XML-Datei bei
Swagger einbinden

53. Kommentare werden in der
Dokumentation angezeigt

54. Ebenfalls Data-Annotations
werden dokumentiert

55. Weitere Informationen über
remarks-Tag anzeigen lassen

56. Die Anzeige der weiteren
Informationen

57. Warnungen
entfernen

58. Beim Builden werden
Warnungen angezeigt

59. In die Eigenschaften wechseln,
mit einem Doppelklick auf
Properties.

60. Warnungs-Codes zum
Ignorieren eintragen

61. Build läuft ohne
Warnungen

62. Zusätzliche
API-Informationen

63. Allgemeine Informationen
hinterlegen

64. Die Anzeige der
allgemeinen Informationen

65. Was haben wir bis jetzt gelernt?
▪ Die OpenAPI-Spezifikation ist die Basis für Swagger UI
▪ XML-Kommentare zu Aktionen, Klassen und
Eigenschaften können in die Spezifikation übersetzt
werden
▪ Datenanmerkungen wirken sich auf die Spezifikation aus
▪ Eine Spezifikation sollte eine allgemeine Beschreibung
der API enthalten

66. Konventionen für die OpenAPI

67. Der
ApiExplorer

68. Der ApiExplorer ist eine Abstraktion über
ASP
.NET Core MVC, die Metadaten zu dieser
Anwendung verfügbar macht.

69. Swashbuckle verwendet die Metadaten, die
ApiExplorer verfügbar macht, um eine OpenAPI-
Spezifikation zu generieren.

70. Der ApiExplorer ist
standardmäßig aktiviert.

71. Eine OpenAPI-Spezifikation sollte alle
möglichen Antworttypen (404, 422, ...) für
die Ressourcen-URI enthalten.

72. Das Ermöglicht Verbrauchern,
entsprechend zu handeln.

73. Unsere Spezifikation muss mit der
Realität unserer API übereinstimmen.

74. Die Statuscodes werden
nicht angezeigt

75. ProducesResponseType-
Attribute helfen hierbei

76. Ebenfalls können generische
Rückgabetypen festgelegt werden

77. Die Statuscodes werden jetzt in
der Dokumentation angezeigt

78. Den ApiExplorer installieren

79. API Analyzer in der
Solution-Datei aktivieren

80. Warnungs-Codes für den
API Analyzer entfernen

81. Der Analyzer zeigt
gefundene Probleme an

82. Durch das integrierte Tooling können
diese einfach behoben werden

83. Attribute über der Klasse, sind
automatisch für alle Methoden gültig

84. Nicht alle möglichen Statuscodes
konnten ermitteln werden

85. Attribute können ebenfalls
Global festgelegt werden

86. Eine alternative wären die
Standard API Konventionen

87. Eigene
Konventionen

88. Ein Post gibt per Standard
einen 201-Statuscode

89. Wird nur der Methoden-Name geändert,
wird der Statuscode falsch ermittelt

90. Eine eigene Konvention
hilft bei diesem Problem

91. Eigene Konvention
zuweisen

92. Der richtige Statuscode
wird angezeigt

93. Dieser kann ebenfalls für die ganze
Klasse automatisch aktiviert werden

94. Oh! Wieder falsch?

95. Match-Regeln
müssen dazu

96. Puh.. Glück gehabt!

97. Attribute
Verwende Attribute anstelle von Konventionen.
Konventionen
Werden von Attributen überschrieben.
Ein Fehler kann schwerwiegende Folgen
haben.
Gut für sehr einfache APIs, nicht geeignet für
umfangreichere APIs

98. Verwende den API Analyzer, aber verlasse Dich nicht
darauf, eine vollständige Abdeckung zu erhalten.

99. Verwende ProducesDefaultResponseType, aber
gebe nach Möglichkeit den genauen Typ an.

100. Wende Attribute nach
Möglichkeit global an.

101. Was haben wir bis jetzt gelernt?
▪ Verwende das ProducesResponseType-Attribut, um
die möglichen Antworttypen (Statuscodes)
anzugeben.
▪ Verwende den API-Analyzer, um diese zu ermitteln
(aber verlasse dich nicht nur auf sie).
▪ Bevorzuge Attribute gegenüber Konventionen

102. Umfangreiche Requests
und Responses

103. Content Negotiation
(Inhaltsvereinbarung)

104. Die Content Negotiation ist der Mechanismus, mit dem
verschiedene Darstellungen einer Ressource an derselben
URI bereitgestellt werden können.

105. Format beim Header der Anfrage festlegen
Accept: application/xml, text/xml
Anfrage-Header
Antwort-Header
Content Type: application/xml

106. Zusätzlicher XML Serializer
Support

107. Vendor-Spezifischer Media Type
application/vnd.marvin.hateoas+json
Top-level type
Vendor prefix
Vendor identifier
Media type name
Suffix

108. Eigenen Media-Type
festlegen

109. HATEOAS nur bei
MediaType-Anfrage

110. GetCamp abfrage
mit der Swagger UI

111. Neuer Media-Type
steht zur Verfügung

112. Semantic
Media Types

113. Semantische Medientypen sind
Medientypen, die etwas über die Bedeutung
der Daten aussagen.

114. REST API
Client
/conference/speaker/1
application/vnd.marvin.speaker.friendly+json
JSON
{
"name": "Gregor Biswanger"
}
/conference/speaker/1
application/vnd.marvin.speaker.full+json
JSON
{
"firstName": "Gregor",
"lastName": "Biswanger"
}

115. Die CampModel-Klasse kopieren
und in CampFriendlyModel-
Klasse umbenennen.

116. Name- und Moniker-
Property zusammenführen

117. Neues Mapping für
AutoMapper festlegen

118. Helper-Attribute für Media-Types
https://pastebin.com/swmhV5gX

119. GetCamp-Methode
kopieren und anpassen

120. OpenAPI Problem mit zwei
gleichen HTTP-Methoden

121. Filter für gleiche HTTP-Methoden
https://pastebin.com/ga0AJ9s0

122. Neuen Operation-Filter
registrieren

123. ApiExplorer soll diese
Methode ignorieren

124. GetCamp hat jetzt einen
Semantic Media Type

125. Semantic Media Types für
eingehende Daten

126. Neues DTO mit weniger
Daten anlegen

127. Neues Mapping für
AutoMapper festlegen

128. Insert Methode kopieren und
mit neuen DTO als Parameter

129. Neuen Operation Filter für die
InsertSimpleCamp Methode

130. Neuen Operation-Filter
registrieren

131. Insert-Post ausführen mit
neuem Semantic Media-Type

132. Was haben wir bis jetzt gelernt?
▪ Verwende herstellerspezifische Medientypen, um
den tatsächlichen Datentyp anzugeben.
▪ OpenAPI 3 ermöglicht die Variation des Schemas
nach Medientyp.
▪ Verwende den lOperationFilter, um die
Unterstützung in Swashbuckle zu implementieren.

133. Versionierung

134. Arbeiten mit mehreren
OpenAPI-Spezifikationen

135. API-Dokumentation in
zwei Gruppen erzeugen

136. Zwei Endpunkte bei
Swagger UI registrieren

137. Controller in
Gruppe zuweisen

138. Controller in
Gruppe zuweisen

139. Unterschiedliche Gruppen
stehen zur Auswahl

140. Nur Speaker-Gruppe
wird angezeigt

141. API
Versionierung

142. Bei einer Veränderung der Umgebung, wird oft
eine API Versionierung notwendig.

143. Eine neue API Version sollte nicht,
durch neue Produkte entstehen.

144. Zum Vergleich einer Assembly Versionierung,
sind API Versionierungen um einiges härter.

145. Bestehende Clients sollen weiterhin konsumieren
können, ohne einem Betriebsausfall.

146. Unterschiedliche
Versionierungsmöglichkeiten

147. URI Pfad
https://../api/v2/customers

148. Query String
https://../api/customers?v=2.0

149. Versionierung durch Headers
GET /api/people/1 HTTP/1.1
Host: swapi.dev
Cache-Control: no-cache
Referer: http://swapi.dev/api/people/
X-Version: 2.0

150. Versionierung durch den Accept Header
GET /api/people/1 HTTP/1.1
Host: swapi.dev
Cache-Control: no-cache
Referer: http://swapi.dev/api/people/
Accept: application/json;version=2.0

151. Versionierung
hinzufügen

152. ASP.NET Core Versioning
installieren

153. CampsController kopieren
und umbenennen.

154. Neue Version festlegen
und Umbenennen

155. Neuen Rückgabe-Typen
implementieren

156. Versionierungen in Route bei
allen Controllern übernehmen

157. Url-Path
Versionierungen

158. API Dokumentation für
unterschiedliche Versionen erzeugen

159. Neue Endpunkte bei
Swagger UI registrieren

160. API Dokumentation für
unterschiedliche Versionen

161. Was haben wir bis jetzt gelernt?
▪ Gruppenoperationen über die GroupName-
Eigenschaft in ApiExplorerSettings
▪ Gruppieren der Operationen nach API-Version

162. Basic Authentifizierung
mit OpenAPI

163. Basic Authentication Code
https://pastebin.com/8z2y76P9

164. Basic Authentifizierung
zur API hinzufügen

165. Basic Authentifizierung zur
API-Dokumentation hinzufügen

166. Auth-Middlewares
hinzufügen

167. Autorisierung für den
CampsController aktivieren

168. API-Dokumentation mit
Authentifizierung

169. Anmelden mit den
Benutzerdaten

170. APIs sind Autorisiert

171. Was haben wir bis jetzt gelernt?
▪ API Authentifizierung mit SecuritySchemes Tags
beschreiben:
▪ AddSecurityDefinition
▪ AddSecurityRequirement

172. Erweiterte Anpassung

173. Für das Anpassen von Kommentaren
wird Markdown verwendet.

174. Markdown für die
Dokumentationskommentare einsetzen

175. Swagger UI zeigt die
Beschreibung formatiert an

176. Unterschiedliche Einstellungen
für die Swagger UI

177. Neue Standard
Darstellung

178. API-Methoden sind über
DeepLinking verfügbar

179. Eigene Farben über eine
eigene CSS-Datei festlegen

180. Eigene CSS-Datei
einbinden

181. Design aus der CSS-Datei
wurde übernommen

182. Was haben wir bis jetzt gelernt?
▪ Für XML-Kommentare kann Markdown verwendet
werden
▪ Halte dich an die grundlegende Markdown-Syntax
▪ Über die Konfigurations-API können wir die
grundlegende Ul-Funktionalität steuern
▪ Für ein erweitertes Branding können wir CSS,
JavaScript einfügen oder die Indexseite vollständig
ersetzen

183. Was haben wir bis jetzt gelernt?
▪ Die OpenAPI-Spezifikation ist die Basis für Swagger UI
▪ XML-Kommentare zu Aktionen, Klassen und
Eigenschaften können in die Spezifikation übersetzt
werden
▪ Datenanmerkungen wirken sich auf die Spezifikation aus
▪ Eine Spezifikation sollte eine allgemeine Beschreibung
der API enthalten

184. Was haben wir bis jetzt gelernt?
▪ Verwende das ProducesResponseType-Attribut, um
die möglichen Antworttypen (Statuscodes)
anzugeben.
▪ Verwende den API-Analyzer, um diese zu ermitteln
(aber verlasse dich nicht nur auf sie).
▪ Bevorzuge Attribute gegenüber Konventionen

185. Was haben wir bis jetzt gelernt?
▪ Verwende herstellerspezifische Medientypen, um
den tatsächlichen Datentyp anzugeben.
▪ OpenAPI 3 ermöglicht die Variation des Schemas
nach Medientyp.
▪ Verwende den lOperationFilter, um die
Unterstützung in Swashbuckle zu implementieren.

186. Was haben wir bis jetzt gelernt?
▪ Gruppenoperationen über die GroupName-
Eigenschaft in ApiExplorerSettings
▪ Gruppieren der Operationen nach API-Version

187. Was haben wir bis jetzt gelernt?
▪ API Authentifizierung mit SecuritySchemes Tags
beschreiben:
▪ AddSecurityDefinition
▪ AddSecurityRequirement

188. Was haben wir bis jetzt gelernt?
▪ Für XML-Kommentare kann Markdown verwendet
werden
▪ Halte dich an die grundlegende Markdown-Syntax
▪ Über die Konfigurations-API können wir die
grundlegende Ul-Funktionalität steuern
▪ Für ein erweitertes Branding können wir CSS,
JavaScript einfügen oder die Indexseite vollständig
ersetzen

190. Alle fertige Lösungen als Branch
http://bit.ly/AspSwaggerWorkshop

191. Dieser kostenlose Workshop ist ein Bestandteil meiner
kommerziellen Workshops zu:
▪ Einstieg in ASP
.NET Core (3-5 Tage)
▪ Advanced REST-APIs mit ASP
.NET Core (3 Tage)
▪ Einstieg in GraphQL mit ASP
.NET Core (3 Tage)
▪ Einstieg in gRPC mit ASP
.NET Core (2 Tage)
▪ Einstieg in SignalR mit ASP
.NET Core (2 Tage)
Lust das wir gemeinsam durchstarten bei deiner Firma?
Dann bitte einfach direkt an mich wenden!

192. Kostenlos auf meinem YouTube Kanal:
„.NET Web-API Entwicklung lernen“
http://bit.ly/dotnet-web-api-entwicklung

193. Jeden Freitag live um 20:30 Uhr auf Twitch.
http://twitch.tv/GregorBiswanger

194. http://about.me/Gregor.Biswanger
Ich freue mich auf Feedback!
Vielen Dank!