Diese Präsentation wurde erfolgreich gemeldet.
Die SlideShare-Präsentation wird heruntergeladen. ×

Hands-on Workshop: API-Dokumentation mit OpenAPI / Swagger in ASP.NET Core

Anzeige
Anzeige
Anzeige
Anzeige
Anzeige
Anzeige
Anzeige
Anzeige
Anzeige
Anzeige
Anzeige
Anzeige
Wird geladen in …3
×

Hier ansehen

1 von 194 Anzeige

Hands-on Workshop: API-Dokumentation mit OpenAPI / Swagger in ASP.NET Core

Herunterladen, um offline zu lesen

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.

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.

Anzeige
Anzeige

Weitere Verwandte Inhalte

Diashows für Sie (20)

Ähnlich wie Hands-on Workshop: API-Dokumentation mit OpenAPI / Swagger in ASP.NET Core (20)

Anzeige

Aktuellste (20)

Anzeige

Hands-on Workshop: API-Dokumentation mit OpenAPI / Swagger in ASP.NET Core

  1. 1. API-Dokumentation mit OpenAPI/Swagger für ASP .NET Core Gregor Biswanger | Freier Berater, Trainer und Autor about.me/gregor.biswanger
  2. 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. 3. Kostenlos auf meinem YouTube Kanal: „.NET Web-API Entwicklung lernen“ http://bit.ly/dotnet-web-api-entwicklung
  4. 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. 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. 6. Eine echte RESTfull API sollte immer den Konsumenten mit seinen Möglichkeiten selbst führen können.
  7. 7. Allerdings ist eine pragmatische HTTP-API die am häufigsten zum Einsatz kommt.
  8. 8. Diese erfordern für ein besseres Verständnis, einen Wegweiser mittels API-Dokumentation.
  9. 9. Ebenfalls ist eine API-Dokumentation für beide varianten relevant um detaillierte Informationen zu bieten.
  10. 10. Zum Beispiel: Security, Zugriffseinschränkungen und weitere Sonderfälle.
  11. 11. Mithilfe der OpenAPI-Spezifikation können wir unsere API Funktionen beschreiben.
  12. 12. Diese ist standardisiert und im JSON- oder YAML-Format.
  13. 13. Swagger ist eine Sammlung von Open-Source- Werkzeugen, um HTTP-Webservices zu entwerfen, zu erstellen, zu dokumentieren und zu nutzen.
  14. 14. Swagger benutzt dazu den Beschreibungsstandard OpenAPI.
  15. 15. OpenAPI-Komponenten und -Tools REST API Code Web UI API Tests JSON YAML OpenAPI Swagger Swagger
  16. 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. 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. 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. 19. Swashbuckle.AspNetCore hilft bei der Arbeit mit OpenAPI in ASP.NET Core
  20. 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. 21. Setup und Start
  22. 22. Visual Studio 2019 und das .NET Core SDK unter www.asp.net
  23. 23. Download der Vorlage http://bit.ly/AspSwaggerWorkshop
  24. 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. 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. 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. 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. 28. Postman herunterladen und installieren www.postman.com/downloads
  29. 29. Kestrel Web-Server auswählen und starten
  30. 30. Meine erste App-Dokumentation
  31. 31. Unsere Ressourcen Camp Talk Speaker Location
  32. 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. 33. Swashbuckle hinzufügen
  34. 34. Swashbuckle ist bereits installiert
  35. 35. Swagger unter Services registrieren
  36. 36. Die Swagger-Middleware einbinden
  37. 37. Die automatisch erzeugte OpenAPI JSON-Datei
  38. 38. Allgemeine Informationen API-Routen + Meta-Daten DTO´s + Meta-Daten
  39. 39. Swagger UI hinzufügen
  40. 40. Die Swagger UI- Middleware einbinden
  41. 41. Projekt ausführen und die Swagger UI im Browser öffnen
  42. 42. API-Route öffnen und zum Testen auswählen
  43. 43. API-Anfrage abschicken
  44. 44. Die Antwort wird direkt darunter angezeigt
  45. 45. Benutzerdefinierte Route für die Swagger UI festlegen
  46. 46. Swagger UI über die neue URL öffnen
  47. 47. XML-Dokumentationskommentare hinzufügen
  48. 48. XML-Dokumentationskommentar hinzufügen
  49. 49. In die Eigenschaften wechseln, mit einem Doppelklick auf Properties.
  50. 50. XML-Dokumentationskommentare für das Projekt aktivieren
  51. 51. Fester Pfad zur XML- Datei entfernen
  52. 52. XML-Datei bei Swagger einbinden
  53. 53. Kommentare werden in der Dokumentation angezeigt
  54. 54. Ebenfalls Data-Annotations werden dokumentiert
  55. 55. Weitere Informationen über remarks-Tag anzeigen lassen
  56. 56. Die Anzeige der weiteren Informationen
  57. 57. Warnungen entfernen
  58. 58. Beim Builden werden Warnungen angezeigt
  59. 59. In die Eigenschaften wechseln, mit einem Doppelklick auf Properties.
  60. 60. Warnungs-Codes zum Ignorieren eintragen
  61. 61. Build läuft ohne Warnungen
  62. 62. Zusätzliche API-Informationen
  63. 63. Allgemeine Informationen hinterlegen
  64. 64. Die Anzeige der allgemeinen Informationen
  65. 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. 66. Konventionen für die OpenAPI
  67. 67. Der ApiExplorer
  68. 68. Der ApiExplorer ist eine Abstraktion über ASP .NET Core MVC, die Metadaten zu dieser Anwendung verfügbar macht.
  69. 69. Swashbuckle verwendet die Metadaten, die ApiExplorer verfügbar macht, um eine OpenAPI- Spezifikation zu generieren.
  70. 70. Der ApiExplorer ist standardmäßig aktiviert.
  71. 71. Eine OpenAPI-Spezifikation sollte alle möglichen Antworttypen (404, 422, ...) für die Ressourcen-URI enthalten.
  72. 72. Das Ermöglicht Verbrauchern, entsprechend zu handeln.
  73. 73. Unsere Spezifikation muss mit der Realität unserer API übereinstimmen.
  74. 74. Die Statuscodes werden nicht angezeigt
  75. 75. ProducesResponseType- Attribute helfen hierbei
  76. 76. Ebenfalls können generische Rückgabetypen festgelegt werden
  77. 77. Die Statuscodes werden jetzt in der Dokumentation angezeigt
  78. 78. Den ApiExplorer installieren
  79. 79. API Analyzer in der Solution-Datei aktivieren
  80. 80. Warnungs-Codes für den API Analyzer entfernen
  81. 81. Der Analyzer zeigt gefundene Probleme an
  82. 82. Durch das integrierte Tooling können diese einfach behoben werden
  83. 83. Attribute über der Klasse, sind automatisch für alle Methoden gültig
  84. 84. Nicht alle möglichen Statuscodes konnten ermitteln werden
  85. 85. Attribute können ebenfalls Global festgelegt werden
  86. 86. Eine alternative wären die Standard API Konventionen
  87. 87. Eigene Konventionen
  88. 88. Ein Post gibt per Standard einen 201-Statuscode
  89. 89. Wird nur der Methoden-Name geändert, wird der Statuscode falsch ermittelt
  90. 90. Eine eigene Konvention hilft bei diesem Problem
  91. 91. Eigene Konvention zuweisen
  92. 92. Der richtige Statuscode wird angezeigt
  93. 93. Dieser kann ebenfalls für die ganze Klasse automatisch aktiviert werden
  94. 94. Oh! Wieder falsch?
  95. 95. Match-Regeln müssen dazu
  96. 96. Puh.. Glück gehabt!
  97. 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. 98. Verwende den API Analyzer, aber verlasse Dich nicht darauf, eine vollständige Abdeckung zu erhalten.
  99. 99. Verwende ProducesDefaultResponseType, aber gebe nach Möglichkeit den genauen Typ an.
  100. 100. Wende Attribute nach Möglichkeit global an.
  101. 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. 102. Umfangreiche Requests und Responses
  103. 103. Content Negotiation (Inhaltsvereinbarung)
  104. 104. Die Content Negotiation ist der Mechanismus, mit dem verschiedene Darstellungen einer Ressource an derselben URI bereitgestellt werden können.
  105. 105. Format beim Header der Anfrage festlegen Accept: application/xml, text/xml Anfrage-Header Antwort-Header Content Type: application/xml
  106. 106. Zusätzlicher XML Serializer Support
  107. 107. Vendor-Spezifischer Media Type application/vnd.marvin.hateoas+json Top-level type Vendor prefix Vendor identifier Media type name Suffix
  108. 108. Eigenen Media-Type festlegen
  109. 109. HATEOAS nur bei MediaType-Anfrage
  110. 110. GetCamp abfrage mit der Swagger UI
  111. 111. Neuer Media-Type steht zur Verfügung
  112. 112. Semantic Media Types
  113. 113. Semantische Medientypen sind Medientypen, die etwas über die Bedeutung der Daten aussagen.
  114. 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. 115. Die CampModel-Klasse kopieren und in CampFriendlyModel- Klasse umbenennen.
  116. 116. Name- und Moniker- Property zusammenführen
  117. 117. Neues Mapping für AutoMapper festlegen
  118. 118. Helper-Attribute für Media-Types https://pastebin.com/swmhV5gX
  119. 119. GetCamp-Methode kopieren und anpassen
  120. 120. OpenAPI Problem mit zwei gleichen HTTP-Methoden
  121. 121. Filter für gleiche HTTP-Methoden https://pastebin.com/ga0AJ9s0
  122. 122. Neuen Operation-Filter registrieren
  123. 123. ApiExplorer soll diese Methode ignorieren
  124. 124. GetCamp hat jetzt einen Semantic Media Type
  125. 125. Semantic Media Types für eingehende Daten
  126. 126. Neues DTO mit weniger Daten anlegen
  127. 127. Neues Mapping für AutoMapper festlegen
  128. 128. Insert Methode kopieren und mit neuen DTO als Parameter
  129. 129. Neuen Operation Filter für die InsertSimpleCamp Methode
  130. 130. Neuen Operation-Filter registrieren
  131. 131. Insert-Post ausführen mit neuem Semantic Media-Type
  132. 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. 133. Versionierung
  134. 134. Arbeiten mit mehreren OpenAPI-Spezifikationen
  135. 135. API-Dokumentation in zwei Gruppen erzeugen
  136. 136. Zwei Endpunkte bei Swagger UI registrieren
  137. 137. Controller in Gruppe zuweisen
  138. 138. Controller in Gruppe zuweisen
  139. 139. Unterschiedliche Gruppen stehen zur Auswahl
  140. 140. Nur Speaker-Gruppe wird angezeigt
  141. 141. API Versionierung
  142. 142. Bei einer Veränderung der Umgebung, wird oft eine API Versionierung notwendig.
  143. 143. Eine neue API Version sollte nicht, durch neue Produkte entstehen.
  144. 144. Zum Vergleich einer Assembly Versionierung, sind API Versionierungen um einiges härter.
  145. 145. Bestehende Clients sollen weiterhin konsumieren können, ohne einem Betriebsausfall.
  146. 146. Unterschiedliche Versionierungsmöglichkeiten
  147. 147. URI Pfad https://../api/v2/customers
  148. 148. Query String https://../api/customers?v=2.0
  149. 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. 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. 151. Versionierung hinzufügen
  152. 152. ASP.NET Core Versioning installieren
  153. 153. CampsController kopieren und umbenennen.
  154. 154. Neue Version festlegen und Umbenennen
  155. 155. Neuen Rückgabe-Typen implementieren
  156. 156. Versionierungen in Route bei allen Controllern übernehmen
  157. 157. Url-Path Versionierungen
  158. 158. API Dokumentation für unterschiedliche Versionen erzeugen
  159. 159. Neue Endpunkte bei Swagger UI registrieren
  160. 160. API Dokumentation für unterschiedliche Versionen
  161. 161. Was haben wir bis jetzt gelernt? ▪ Gruppenoperationen über die GroupName- Eigenschaft in ApiExplorerSettings ▪ Gruppieren der Operationen nach API-Version
  162. 162. Basic Authentifizierung mit OpenAPI
  163. 163. Basic Authentication Code https://pastebin.com/8z2y76P9
  164. 164. Basic Authentifizierung zur API hinzufügen
  165. 165. Basic Authentifizierung zur API-Dokumentation hinzufügen
  166. 166. Auth-Middlewares hinzufügen
  167. 167. Autorisierung für den CampsController aktivieren
  168. 168. API-Dokumentation mit Authentifizierung
  169. 169. Anmelden mit den Benutzerdaten
  170. 170. APIs sind Autorisiert
  171. 171. Was haben wir bis jetzt gelernt? ▪ API Authentifizierung mit SecuritySchemes Tags beschreiben: ▪ AddSecurityDefinition ▪ AddSecurityRequirement
  172. 172. Erweiterte Anpassung
  173. 173. Für das Anpassen von Kommentaren wird Markdown verwendet.
  174. 174. Markdown für die Dokumentationskommentare einsetzen
  175. 175. Swagger UI zeigt die Beschreibung formatiert an
  176. 176. Unterschiedliche Einstellungen für die Swagger UI
  177. 177. Neue Standard Darstellung
  178. 178. API-Methoden sind über DeepLinking verfügbar
  179. 179. Eigene Farben über eine eigene CSS-Datei festlegen
  180. 180. Eigene CSS-Datei einbinden
  181. 181. Design aus der CSS-Datei wurde übernommen
  182. 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. 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. 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. 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. 186. Was haben wir bis jetzt gelernt? ▪ Gruppenoperationen über die GroupName- Eigenschaft in ApiExplorerSettings ▪ Gruppieren der Operationen nach API-Version
  187. 187. Was haben wir bis jetzt gelernt? ▪ API Authentifizierung mit SecuritySchemes Tags beschreiben: ▪ AddSecurityDefinition ▪ AddSecurityRequirement
  188. 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
  189. 189. Alle fertige Lösungen als Branch http://bit.ly/AspSwaggerWorkshop
  190. 190. 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!
  191. 191. Kostenlos auf meinem YouTube Kanal: „.NET Web-API Entwicklung lernen“ http://bit.ly/dotnet-web-api-entwicklung
  192. 192. Jeden Freitag live um 20:30 Uhr auf Twitch. http://twitch.tv/GregorBiswanger
  193. 193. http://about.me/Gregor.Biswanger Ich freue mich auf Feedback! Vielen Dank!

×