Successfully reported this slideshow.
We use your LinkedIn profile and activity data to personalize ads and to show you more relevant ads. You can change your ad preferences anytime.

.NET Fest 2019. Kevin Dockx. Uncovering Swagger/OpenAPI

32 views

Published on

If you've ever had to document an API, chances are you've used Swagger (OpenAPI) for it. But what IS that, exactly?
In this session we'll dive underneath the covers of OpenAPI. We'll cover documenting an ASP.NET Core API, but we won't stop there: we'll also learn how OpenAPI can help with API test generation and code generation

Published in: Education
  • Be the first to comment

  • Be the first to like this

.NET Fest 2019. Kevin Dockx. Uncovering Swagger/OpenAPI

  1. 1. KEVINDOCKX https://www.kevindockx.com UNCOVERING SWAGGER/ OPENAPI In this session, you’ll learn all about documenting your API with OpenAPI (Swagger)
  2. 2. KEVINDOCKX MARVIN HI, I’M KEVIN @KevinDockx https://www.kevindockx.com https://github.com/KevinDockx Freelance solution architect focused on APIs and security Microsoft MVP Pluralsight Author 2
  3. 3. KEVINDOCKX MARVIN COMING UP Why use OpenAPI to document your API? Clearing up the terminology confusion The importance of ApiExplorer Producing correct response types Analyzers to the rescue Advanced content negotiation & schema variation by media type 3
  4. 4. KEVINDOCKX MARVIN WHY USE SWAGGER / OPENAPI TO DOCUMENT YOURAPI? 4 Public APIs need documentation, but so do in-company APIs Documentation leads to knowledge leads to adoption Clear documentation saves time and money
  5. 5. KEVINDOCKX MARVIN An OpenAPI specification describes the capabilities of your API, and how to interact with it It’s standardized, and in JSON or YAML format 5
  6. 6. KEVINDOCKX MARVIN OPENAPI COMPONENTS AND TOOLS
  7. 7. KEVINDOCKX MARVIN OPENAPI COMPONENTS AND TOOLS 7 Full specification https://bit.ly/2yuDTKX OpenAPI 3 is the current version “Swagger” can be used, but “OpenAPI” is the preferred term
  8. 8. KEVINDOCKX MARVIN CLEARING UP THE TERMINOLOGY CONFUSION 8 OpenAPI specification and Swagger specification are the same thing Swagger is a set of open-source built around that OpenAPI specification
  9. 9. KEVINDOCKX MARVIN Swagger Editor helps with creating the specification Swagger UI renders a documentation UI from the specification Swagger Codegen consists of a set of tools that help with generating client classes, tests, … from the specification SWAGGER IN DETAIL
  10. 10. KEVINDOCKX MARVIN CLEARING UP THE TERMINOLOGY CONFUSION 10 OpenAPI specification and Swagger specification are the same thing Swagger is a set of open-source built around that OpenAPI specification Swashbuckle.AspNetCore helps with working with OpenAPI in ASP.NET Core
  11. 11. KEVINDOCKX MARVIN Standards-based development allows you to mix and match components based on that standard 11
  12. 12. KEVINDOCKX MARVIN DEMO TIME Time to dive into code 12
  13. 13. KEVINDOCKX MARVIN Design your contract first. Implement it later. I like paper. But creating the contract with OpenAPI is probably better. 13
  14. 14. KEVINDOCKX MARVIN ApiExplorer is an abstraction on top of ASP.NET Core MVC that exposes metadata about that application 14
  15. 15. KEVINDOCKX MARVIN THE IMPORTANCE OFAPIEXPLORER 15 Swashbuckle uses the metadata ApiExplorer exposes to generate an OpenAPI specification ApiExplorer is enabled by default It’s registered when calling services.AddMvc() (AddControllers in Core 3)
  16. 16. KEVINDOCKX MARVIN PRODUCING CORRECT RESPONSE TYPES 16 An OpenAPI specification should include all possible response types (404, 422, …) for a method/resource URI Allows consumers to act accordingly Our specification must match the reality of our API
  17. 17. KEVINDOCKX MARVIN DEMO TIME Time to dive into code 17
  18. 18. KEVINDOCKX MARVIN ANALYZERS TO THE RESCUE 18 Analyzers analyse your code and help improving it Microsoft.AspNetCore.Mvc.Api.Analyzers
  19. 19. KEVINDOCKX MARVIN DEMO TIME Time to dive into code 19
  20. 20. KEVINDOCKX MARVIN Use API Analyzer, but don't rely on it to give you full coverage You (should ) know better how your API should behave than a tool 20
  21. 21. KEVINDOCKX MARVIN Content negotiation is the mechanism used for serving different representations of a resource at the same URI 21
  22. 22. KEVINDOCKX MARVIN CONTENT NEGOTIATION GET api/movies/{id} { movie in JSON} { movie in XML} movie
  23. 23. KEVINDOCKX MARVIN CONTENT NEGOTIATION GET api/movies/{id} { movie in JSON} movie Accept: application/json
  24. 24. KEVINDOCKX MARVIN CONTENT NEGOTIATION GET api/movies/{id} { movie in XML} movie Accept: application/xml
  25. 25. KEVINDOCKX MARVIN “application/json” tells us something about the format of the representation, but nothing about the actual type 25
  26. 26. KEVINDOCKX MARVIN ADVANCED CONTENT NEGOTIATION GET api/movies/{id} movie { "authorFirstName": "Stephen", "authorLastName ": "King", … } { "author": "Stephen King", … } application/json? application/json?
  27. 27. KEVINDOCKX MARVIN ADVANCED CONTENT NEGOTIATION GET api/movies/{id} movie { "authorFirstName": "Stephen", "authorLastName ": "King", … } { "author": "Stephen King", … } application/json application/vnd.marvin.book+json application/vnd.marvin. bookwithconcatenateddirectorname+json
  28. 28. KEVINDOCKX MARVIN SCHEMAVARIATION BY MEDIATYPE Supported since OpenAPI 3 Swashbuckle doesn’t support this out of the box at the moment "responses":{ "200":{ "description":"Returnstherequestedbook", "content": { "application/vnd.marvin.book+json":{ "schema":{"$ref": "#/components/schemas/Book" }}, "application/json":{ "schema":{"$ref": "#/components/schemas/Book" }}, "application/vnd.marvin.bookwithconcatenatedauthorname+json":{ "schema":{"$ref": "#/components/schemas/BookWithConcatenatedAuthorName" }}}}
  29. 29. KEVINDOCKX MARVIN ADDITIONAL RESOURCES Demo code on my Github https://github.com/KevinDockx/ My Pluralsight Courses https://app.pluralsight.com/profile/author/kevin-dockx 29
  30. 30. THANK YOU

×