TT Webinar 2020 OpenApi

Slides zu meinem API-Dokumentation mit Swagger Webinar vom 29. April 2020

Transcript

2. ▪ 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 ▪ sebastian.gingter@thinktecture.com ▪ Twitter: @phoenixhawk Advanced ASP.NET Core Web APIs
3. 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
4. Advanced ASP.NET Core Web APIs
5. Advanced ASP.NET Core Web APIs
6. 6 Advanced ASP.NET Core Web APIs
7. Advanced ASP.NET Core Web APIs
8. Advanced ASP.NET Core Web APIs
9. 9 Initiative Kurzum: OpenAPI = Spezifikation / Standard Swagger = Werkzeuge Advanced ASP.NET Core Web APIs
10. 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
11. Advanced ASP.NET Core Web APIs
12. 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
13. 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
14. Advanced ASP.NET Core Web APIs
15. Advanced ASP.NET Core Web APIs
16. 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
17. Advanced ASP.NET Core Web APIs
18. 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
19. 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
20. 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
21. 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
22. 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
23. 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
24. @phoenixhawk sebastian.gingter@thinktecture.com