Basta Fall 2019 OpenAPI

Basta Fall 2019 OpenAPI

This session shows how to document your ASP.NET Core Web API using Swashbuckle Swagger, enrich the resulting document, use that to automatically generate client code for API usage and postman collections for testing.

Sample code can be found at: https://github.com/thinktecture/basta-fall-2019-openapi

Ebeb5d8fd081058ba8df73d378bf83d7?s=128

Sebastian P.R. Gingter

September 26, 2019
Tweet

Transcript

  1. 1

  2. Advanced ASP.NET Core Web APIs ▪ ▪ ▪ ▪ ▪

    ▪ ▪ ▪ ▪ Twitter:
  3. 4 ▪ ▪ ▪ ☺ ▪ ▪ Advanced ASP.NET Core

    Web APIs
  4. Advanced ASP.NET Core Web APIs

  5. Advanced ASP.NET Core Web APIs Target audience

  6. 7 Advanced ASP.NET Core Web APIs

  7. Advanced ASP.NET Core Web APIs

  8. Advanced ASP.NET Core Web APIs

  9. 10 Advanced ASP.NET Core Web APIs OpenAPI Initiative Linux Foundation

    TL;DR; OpenAPI = Specification Swagger = Tooling
  10. 11 Advanced ASP.NET Core Web APIs IL-Code Meta data Swagger.json

    Documentation Webserver with Swagger UI
  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://github.com/thinktecture/basta-fall-2019-openapi • https://speakerdeck.com/phoenixhawk/basta-fall-2019-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 https://github.com/thinktecture/basta-fall-2019-openapi https://speakerdeck.com/phoenixhawk/basta-fall-2019-openapi