Hands-on Workshop: API-Dokumentation mit OpenAPI / Swagger in ASP.NET Core
0 gefällt mir263 aufrufe
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.
![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](https://image.slidesharecdn.com/api-dokumentationmitopenapi-swagger-210326144613/85/Hands-on-Workshop-API-Dokumentation-mit-OpenAPI-Swagger-in-ASP-NET-Core-26-320.jpg)
Anzeige
Weitere ähnliche Inhalte
Was ist angesagt? (20)
Ähnlich wie Hands-on Workshop: API-Dokumentation mit OpenAPI / Swagger in ASP.NET Core (20)
Anzeige
Mehr von Gregor Biswanger (6)
Anzeige
Hands-on Workshop: API-Dokumentation mit OpenAPI / Swagger in ASP.NET Core
- 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
- 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
- 37. Die automatisch erzeugte OpenAPI JSON-Datei
- 38. Allgemeine Informationen API-Routen + Meta-Daten DTO´s + Meta-Daten
- 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
- 44. Die Antwort wird direkt darunter angezeigt
- 45. Benutzerdefinierte Route für die Swagger UI festlegen
- 46. Swagger UI über die neue URL öffnen
- 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
- 53. Kommentare werden in der Dokumentation angezeigt
- 55. Weitere Informationen über remarks-Tag anzeigen lassen
- 56. Die Anzeige der weiteren Informationen
- 58. Beim Builden werden Warnungen angezeigt
- 59. In die Eigenschaften wechseln, mit einem Doppelklick auf Properties.
- 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
- 76. Ebenfalls können generische Rückgabetypen festgelegt werden
- 77. Die Statuscodes werden jetzt in der Dokumentation angezeigt
- 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
- 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
- 92. Der richtige Statuscode wird angezeigt
- 93. Dieser kann ebenfalls für die ganze Klasse automatisch aktiviert werden
- 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
- 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
- 107. Vendor-Spezifischer Media Type application/vnd.marvin.hateoas+json Top-level type Vendor prefix Vendor identifier Media type name Suffix
- 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
- 120. OpenAPI Problem mit zwei gleichen HTTP-Methoden
- 121. Filter für gleiche HTTP-Methoden https://pastebin.com/ga0AJ9s0
- 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
- 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
- 135. API-Dokumentation in zwei Gruppen erzeugen
- 136. Zwei Endpunkte bei Swagger UI registrieren
- 139. Unterschiedliche Gruppen stehen zur Auswahl
- 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.
- 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
- 154. Neue Version festlegen und Umbenennen
- 156. Versionierungen in Route bei allen Controllern übernehmen
- 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
- 164. Basic Authentifizierung zur API hinzufügen
- 165. Basic Authentifizierung zur API-Dokumentation hinzufügen
- 167. Autorisierung für den CampsController aktivieren
- 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
- 178. API-Methoden sind über DeepLinking verfügbar
- 179. Eigene Farben über eine eigene CSS-Datei festlegen
- 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!