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

Transcript

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