Upgrade to Pro — share decks privately, control downloads, hide ads and more …

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

Sebastian Gingter

February 27, 2020
Tweet

More Decks by Sebastian Gingter

Other Decks in Technology

Transcript

  1. 1

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

    Advanced ASP.NET Core Web APIs
  3. 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
  4. 13 • dotnet new webapi • • /api/weatherForecast • •

    • /weatherForecast, /health, /article • /weatherForecast (paged), /health, /article (paged) • /health, /article (paged) Advanced ASP.NET Core Web APIs
  5. 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
  6. 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
  7. 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
  8. 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
  9. 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
  10. 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
  11. 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
  12. 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