Slide 1
Slide 1 text
1
Slide 2
Slide 2 text
Advanced ASP.NET Core Web APIs
▪
▪
▪
▪
▪
▪
▪
▪
▪ Twitter:
Slide 3
Slide 3 text
4
▪
▪
▪ ☺
▪
▪
Advanced ASP.NET Core Web APIs
Slide 4
Slide 4 text
Advanced ASP.NET Core Web APIs
Slide 5
Slide 5 text
Advanced ASP.NET Core Web APIs
Target audience
Slide 6
Slide 6 text
7
Advanced ASP.NET Core Web APIs
Slide 7
Slide 7 text
Advanced ASP.NET Core Web APIs
Slide 8
Slide 8 text
Advanced ASP.NET Core Web APIs
Slide 9
Slide 9 text
10
Advanced ASP.NET Core Web APIs
OpenAPI Initiative
Linux Foundation
TL;DR;
OpenAPI = Specification
Swagger = Tooling
Slide 10
Slide 10 text
11
Advanced ASP.NET Core Web APIs
IL-Code
Meta data
Swagger.json
Documentation
Webserver with Swagger UI
Slide 11
Slide 11 text
Advanced ASP.NET Core Web APIs
Slide 12
Slide 12 text
13
• dotnet new webapi
•
• /api/weatherForecast
•
•
• /weatherForecast, /health, /article
• /weatherForecast (paged), /health, /article (paged)
• /health, /article (paged)
Advanced ASP.NET Core Web APIs
Slide 13
Slide 13 text
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
Slide 14
Slide 14 text
Advanced ASP.NET Core Web APIs
Slide 15
Slide 15 text
Advanced ASP.NET Core Web APIs
Slide 16
Slide 16 text
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
Slide 17
Slide 17 text
Advanced ASP.NET Core Web APIs
Slide 18
Slide 18 text
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
Slide 19
Slide 19 text
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
Slide 20
Slide 20 text
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
Slide 21
Slide 21 text
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
Slide 22
Slide 22 text
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
Slide 23
Slide 23 text
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
Slide 24
Slide 24 text
@phoenixhawk
[email protected]
https://github.com/thinktecture/basta-fall-2019-openapi
https://speakerdeck.com/phoenixhawk/basta-fall-2019-openapi