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.
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.
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
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
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
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.
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
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.
161. Was haben wir bis jetzt gelernt?
▪ Gruppenoperationen über die GroupName-
Eigenschaft in ApiExplorerSettings
▪ Gruppieren der Operationen nach API-Version
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
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