TT Webinar 2020 OpenApi

TT Webinar 2020 OpenApi

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

Ebeb5d8fd081058ba8df73d378bf83d7?s=128

Sebastian P.R. Gingter

April 29, 2020
Tweet

Transcript

  1. None
  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