BASTA Spring 2020 OpenAPI

BASTA Spring 2020 OpenAPI

* Why we need Web API documentation
* What is OpenAPI and Swagger
* Swashbuckle.Swagger can automatically generate that for us
* Swagger UI enables developers to explore our API interactively
* The document can be used to generate client code
* The document can be used to generate test boilerplates
* We don’t have to do that manually and safe a lot of tedious work & time

Ebeb5d8fd081058ba8df73d378bf83d7?s=128

Sebastian P.R. Gingter

February 27, 2020
Tweet

Transcript

  1. 1

  2. ▪ ▪ ▪ ▪ ▪ ▪ ▪ ▪ ▪ Twitter:

    Advanced ASP.NET Core Web APIs
  3. 4 ▪ ▪ ▪ ☺ ▪ ▪ Advanced ASP.NET Core

    Web APIs
  4. Advanced ASP.NET Core Web APIs

  5. Target audience Advanced ASP.NET Core Web APIs

  6. 7 Advanced ASP.NET Core Web APIs

  7. Advanced ASP.NET Core Web APIs

  8. Advanced ASP.NET Core Web APIs

  9. 10 OpenAPI Initiative Linux Foundation TL;DR; OpenAPI = Specification Swagger

    = Tooling Advanced ASP.NET Core Web APIs
  10. 11 IL-Code Meta data Swagger.json Documentation Webserver with Swagger UI

    Swashbuckle.Swagger by Richard Morris SwaggerGen & SwaggerUI Advanced ASP.NET Core Web APIs
  11. Advanced ASP.NET Core Web APIs

  12. 13 • dotnet new webapi • • /api/weatherForecast • •

    • /weatherForecast, /health, /article • /weatherForecast (paged), /health, /article (paged) • /health, /article (paged) Advanced ASP.NET Core Web APIs
  13. 14 • Document methods / endpoints • Document model /

    schema information • Enrich this as much as possible • Exclude certain endpoints from documentation • Enable AuthN & AuthZ with Swagger UI • Combine with API Versioning • Customize documentation UI • Generate client code to consume our API • Test our API Advanced ASP.NET Core Web APIs
  14. Advanced ASP.NET Core Web APIs

  15. Advanced ASP.NET Core Web APIs

  16. 17 • Why we need Web API documentation • What

    is OpenAPI and Swagger • Swashbuckle.Swagger can automatically generate that for us • Swagger UI enables developers to explore our API interactively • The document can be used to generate client code • The document can be used to generate test boilerplates • We don’t have to do that manually and safe a lot of tedious work & time Advanced ASP.NET Core Web APIs
  17. Advanced ASP.NET Core Web APIs

  18. 19 • OpenAPI • Formerly Swagger Specification & Tools by

    Smartbear Software • Open Source as well as commercial / closed source components • Smartbear Software & other companies (Google, IBM & Microsoft) started the Open API Initiative in Nov. 2015 under the umbrella of the Linux Foundation • Smartbear contributed its Swagger specification to the initiative • The initiative released the official OpenAPI specification 3.0 in Oct. 2017 • Smartbear Software continues to maintain their Swagger toolings (Swagger Editor, Swagger CodeGen, Swagger UI, etc.) • TL;DR; • OpenAPI = Specification • Swagger = Tooling Advanced ASP.NET Core Web APIs
  19. 20 • Documentation • Endpoints and data structures / schemas

    • Example data, example calls • Understandable • Explorable • Searchable • Ideally as much automated as possible • Ideally as multi-purpose as possible Advanced ASP.NET Core Web APIs
  20. 21 • .NET (luckily) offers a lot of metadata at

    runtime • Tooling is capable of automatically extracting a lot of documentation-relevant data directly from our IL code • Swashbuckle.Swagger for .NET (Core) projects • From Richard Morris (Getty Images, not Smartbear) • Automatically generates an OpenAPI document (swagger.json) using a custom Swagger Generator • Automatically displays a web page with our Web API documentation using Swagger UI from Smartbear Advanced ASP.NET Core Web APIs
  21. 22 • To be able to use a Web API,

    you need some sort of client • Web API clients usually consist of a ton of boilerplate code • They only differ in parameters, body format, http method and response format • All of that is known and documented • All information in available in our OpenAPI 3.0 document (swagger.json) • We can use that to automatically generate clients Advanced ASP.NET Core Web APIs
  22. 23 • When we write endpoints, we want to make

    sure they really work as expected • Postman helps in manual & automated testing • Setting up all the requests manually is tedious • Postman can import our swagger.json to pre-fill most of our requests • Postman tests use • Chai Assertion Library • tv4 (Tiny Validator for v4 JSON Schema) (marked as deprecated) • Ajv (Another JSON Schema Validator) (still needs manual import) Advanced ASP.NET Core Web APIs
  23. 24 • https://thinktecture.com/sebastian-gingter • https://github.com/thinktecture/basta-spring-2020-openapi • https://speakerdeck.com/phoenixhawk/basta-spring-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 Slides & Code-Samples: https://www.thinktecture.com/sebastian-gingter Coming soon: Advanced ASP.NET

    Core Web API Screencasts Stay tuned: https://thinktecture.com/newsletter