Slide 1
Slide 1 text
No content
Slide 2
Slide 2 text
▪ Consultant bei der Thinktecture AG
▪ Spezialgebiete
▪ Flexible und skalierbare Backend-Architekturen
▪ Identity und Access Management
▪ Entwickler-Produktivität
▪ Softwarequalität
▪ Alles rund um .NET Core
▪ [email protected]
▪ Twitter: @phoenixhawk
Advanced ASP.NET Core Web APIs
Slide 3
Slide 3 text
3
▪ Warum überhaupt Dokumentation?
▪ Wie dokumentiere ich eine ASP.NET Core Web API?
▪ Jede Menge technische Details ☺
▪ Was sonst? API Clients & Tests generieren
▪ Fragen und Antworten
Advanced ASP.NET Core Web APIs
Slide 4
Slide 4 text
Advanced ASP.NET Core Web APIs
Slide 5
Slide 5 text
Advanced ASP.NET Core Web APIs
Slide 6
Slide 6 text
6
Advanced ASP.NET Core Web APIs
Slide 7
Slide 7 text
Advanced ASP.NET Core Web APIs
Slide 8
Slide 8 text
Advanced ASP.NET Core Web APIs
Slide 9
Slide 9 text
9
Initiative
Kurzum:
OpenAPI = Spezifikation / Standard
Swagger = Werkzeuge
Advanced ASP.NET Core Web APIs
Slide 10
Slide 10 text
10
IL-Code
Metadaten
Swagger.json
Dokumentation
Webserver mit Swagger UI
Swashbuckle.Swagger von Richard Morris (Getty Images)
SwaggerGen & SwaggerUI
Advanced ASP.NET Core Web APIs
Slide 11
Slide 11 text
Advanced ASP.NET Core Web APIs
Slide 12
Slide 12 text
12
• dotnet new webapi
• ASP.NET Core 3.1
• Liefert Endpunkt /api/weatherForecast
+ Authentication/Authorization
• IdentityServer Token Validation mit dem Demo IdentityServer
• Policy “api”, benötigt angemeldeten User & den Scope “api”
+ API Versioning & Neue Endpunkte
• v1: /weatherForecast, /health, /article
• v2: /weatherForecast (paged), /health, /article (paged)
• v3: /health, /article (paged)
Advanced ASP.NET Core Web APIs
Slide 13
Slide 13 text
13
• Methoden / Endpunkte (Operationen) dokumentieren
• Datenmodell / Schema-Informationen dokumentieren
• Soweit wie möglich anreichern
• Bestimmte Endpunkte aus der Dokumentation ausnehmen
• Authentication & Authorization einbinden
• API-Versionierung berücksichtigen
• Client-Code aus unserer Dokumentation generieren
• Unsere API Testen
Advanced ASP.NET Core Web APIs
Slide 14
Slide 14 text
Advanced ASP.NET Core Web APIs
Slide 15
Slide 15 text
Advanced ASP.NET Core Web APIs
Slide 16
Slide 16 text
16
• Warum brauchen wir Dokumentation?
• Was ist OpenAPI und was ist Swagger?
• Swashbuckle.Swagger kann eine OpenAPI-Dokumentation für uns generieren
• Swagger UI erlaubt es die Dokumentation zu erleben
• Das Dokument kann zur Generierung von Client-Code verwendet werden
• Das Dokument kann zur Generierung von Postman Collections verwendet werden
• Wir können uns damit eine Menge manueller & fehleranfälliger Arbeit ersparen
Advanced ASP.NET Core Web APIs
Slide 17
Slide 17 text
Advanced ASP.NET Core Web APIs
Slide 18
Slide 18 text
18
• OpenAPI
• Früher Swagger Specification & Tools von Smartbear Software
• Open Source und kommerzielle / closed source Komponenten
• Smartbear Software & andere Firmen (Google, IBM & Microsoft) starten die
Open API Initiative im Nov. 2015 als Teil der Linux Foundation
• Smartbear gibt seine Swagger specification an die OpenAPI Initiative
• Erstes Release der überarbeiteten OpenAPI Specification 3.0 im Oktober 2017
• Smartbear Software arbeitet weiter am Swagger Tooling
(Swagger Editor, Swagger CodeGen, Swagger UI, etc.)
• TL;DR;
• OpenAPI = Spezifikation
• Swagger = Tooling
Advanced ASP.NET Core Web APIs
Slide 19
Slide 19 text
19
• Dokumentation
• Endpunkte und Datenstrukturen / Schemata
• Beispieldaten und Beispiel-Aufrufe
• Verständlich
• Erforsch- bzw. Erlebbar
• Durchsuchbar
• So weit automatisiert wie möglich
• Idealerweise so Vielseitig wie möglich
Advanced ASP.NET Core Web APIs
Slide 20
Slide 20 text
20
• .NET bietet uns viel Metadaten zur Laufzeit
• Swagger-Tooling kann aus diesen Metadaten viele Informationen
extrahieren die für die Dokumentation relevant sind
• Swashbuckle.Swagger für .NET (Core) Projekte
• Author: Richard Morris (Getty Images, nicht Smartbear)
• Generiert automatisch ein OpenAPI Document (swagger.json)
mithilfe eines eigenen Generators
• Liefert ein (leicht) angepasstes SwaggerUI aus, um eine
Dokumentations-Webseite bereitzustellen
Advanced ASP.NET Core Web APIs
Slide 21
Slide 21 text
21
• Um mit einer API zu kommunizieren benötigt
man Client-Code
• Diese Clients bestehen normalerweise aus ungeheuer viel
gleichem Code aus Vorlagen und viel copy&paste
• Unterschiede liegen eigentlich nur in Parametern, Headern,
Format des Bodys (Schema), Http-Methode und Format der Antwort (Schema)
• Alle diese Informationen sind bekannt und dokumentiert
• Alle diese Informationen stehen in unserem
OpenAPI 3.0 Dokument (swagger.json) bereit
• Daraus können wir Clients automatisch generieren
Advanced ASP.NET Core Web APIs
Slide 22
Slide 22 text
22
• Wenn wir Endpunkte schreiben, wollen wir sicherstellen das sie
sich wie erwartet verhalten und funktionieren
• Postman kann bei manuellen und automatisierten Tests helfen
• Alle Tests manuell aufsetzen ist aufwändig und fehleranfällig
• Postman kann unser swagger.json importieren und damit den
Großteil der Requests schon vorausfüllen
• Postman tests verwenden
• Chai Assertion Library
• tv4 (Tiny Validator for v4 JSON Schema) (deprecated)
• Ajv (Another JSON Schema Validator) (muss derzeit noch manuell eingebunden werden)
Advanced ASP.NET Core Web APIs
Slide 23
Slide 23 text
23
• https://github.com/thinktecture/tt-webinar-2020-openapi
• https://speakerdeck.com/phoenixhawk/tt-webinar-2020-openapi
• https://www.openapis.org/
• https://swagger.io/
• https://github.com/domaindrivendev/Swashbuckle.AspNetCore
• https://github.com/microsoft/aspnet-api-versioning
• https://github.com/swagger-api/swagger-codegen
• https://www.getpostman.com/
• https://www.npmjs.com/package/newman
Advanced ASP.NET Core Web APIs