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.
KEVINDOCKX
https://www.kevindockx.com
UNCOVERING
SWAGGER/
OPENAPI
In this session, you’ll learn all
about documenting your...
KEVINDOCKX
MARVIN
HI, I’M KEVIN
@KevinDockx
https://www.kevindockx.com
https://github.com/KevinDockx
Freelance solution ar...
KEVINDOCKX
MARVIN
COMING UP
Why use OpenAPI to document your API?
Clearing up the terminology confusion
The importance of ...
KEVINDOCKX
MARVIN
WHY USE SWAGGER / OPENAPI TO DOCUMENT
YOURAPI?
4
Public APIs need documentation, but so do in-company AP...
KEVINDOCKX
MARVIN
An OpenAPI specification
describes the capabilities
of your API, and how to
interact with it
It’s standa...
KEVINDOCKX
MARVIN
OPENAPI COMPONENTS AND TOOLS
KEVINDOCKX
MARVIN
OPENAPI COMPONENTS AND TOOLS
7
Full specification
https://bit.ly/2yuDTKX
OpenAPI 3 is the current versio...
KEVINDOCKX
MARVIN
CLEARING UP THE TERMINOLOGY CONFUSION
8
OpenAPI specification and Swagger specification are the same
thi...
KEVINDOCKX
MARVIN
Swagger Editor
helps with creating
the specification
Swagger UI renders
a documentation UI
from the
spec...
KEVINDOCKX
MARVIN
CLEARING UP THE TERMINOLOGY CONFUSION
10
OpenAPI specification and Swagger specification are the same
th...
KEVINDOCKX
MARVIN
Standards-based
development allows you to
mix and match components
based on that standard
11
KEVINDOCKX
MARVIN
DEMO TIME Time to dive into code
12
KEVINDOCKX
MARVIN
Design your contract first.
Implement it later.
I like paper. But creating
the contract with OpenAPI
is ...
KEVINDOCKX
MARVIN
ApiExplorer is an
abstraction on top of
ASP.NET Core MVC that
exposes metadata about
that application
14
KEVINDOCKX
MARVIN
THE IMPORTANCE OFAPIEXPLORER
15
Swashbuckle uses the metadata ApiExplorer exposes to
generate an OpenAPI...
KEVINDOCKX
MARVIN
PRODUCING CORRECT RESPONSE TYPES
16
An OpenAPI specification should include all possible
response types ...
KEVINDOCKX
MARVIN
DEMO TIME Time to dive into code
17
KEVINDOCKX
MARVIN
ANALYZERS TO THE RESCUE
18
Analyzers analyse your code and help improving it
Microsoft.AspNetCore.Mvc.Ap...
KEVINDOCKX
MARVIN
DEMO TIME Time to dive into code
19
KEVINDOCKX
MARVIN
Use API Analyzer, but don't
rely on it to give you full
coverage
You (should ) know better
how your API...
KEVINDOCKX
MARVIN
Content negotiation is the
mechanism used for serving
different representations of
a resource at
the sam...
KEVINDOCKX
MARVIN
CONTENT NEGOTIATION
GET api/movies/{id}
{ movie in JSON}
{ movie in XML}
movie
KEVINDOCKX
MARVIN
CONTENT NEGOTIATION
GET api/movies/{id}
{ movie in JSON}
movie
Accept: application/json
KEVINDOCKX
MARVIN
CONTENT NEGOTIATION
GET api/movies/{id}
{ movie in XML}
movie
Accept: application/xml
KEVINDOCKX
MARVIN
“application/json” tells us
something about the format
of the representation, but
nothing about the actu...
KEVINDOCKX
MARVIN
ADVANCED CONTENT NEGOTIATION
GET api/movies/{id}
movie
{
"authorFirstName": "Stephen",
"authorLastName "...
KEVINDOCKX
MARVIN
ADVANCED CONTENT NEGOTIATION
GET api/movies/{id}
movie
{
"authorFirstName": "Stephen",
"authorLastName "...
KEVINDOCKX
MARVIN
SCHEMAVARIATION BY MEDIATYPE
Supported since OpenAPI 3
Swashbuckle doesn’t support this out of the box a...
KEVINDOCKX
MARVIN
ADDITIONAL RESOURCES
Demo code on my Github
https://github.com/KevinDockx/
My Pluralsight Courses
https:...
THANK YOU
Upcoming SlideShare
Loading in …5
×

of

.NET Fest 2019. Kevin Dockx. Uncovering Swagger/OpenAPI Slide 1 .NET Fest 2019. Kevin Dockx. Uncovering Swagger/OpenAPI Slide 2 .NET Fest 2019. Kevin Dockx. Uncovering Swagger/OpenAPI Slide 3 .NET Fest 2019. Kevin Dockx. Uncovering Swagger/OpenAPI Slide 4 .NET Fest 2019. Kevin Dockx. Uncovering Swagger/OpenAPI Slide 5 .NET Fest 2019. Kevin Dockx. Uncovering Swagger/OpenAPI Slide 6 .NET Fest 2019. Kevin Dockx. Uncovering Swagger/OpenAPI Slide 7 .NET Fest 2019. Kevin Dockx. Uncovering Swagger/OpenAPI Slide 8 .NET Fest 2019. Kevin Dockx. Uncovering Swagger/OpenAPI Slide 9 .NET Fest 2019. Kevin Dockx. Uncovering Swagger/OpenAPI Slide 10 .NET Fest 2019. Kevin Dockx. Uncovering Swagger/OpenAPI Slide 11 .NET Fest 2019. Kevin Dockx. Uncovering Swagger/OpenAPI Slide 12 .NET Fest 2019. Kevin Dockx. Uncovering Swagger/OpenAPI Slide 13 .NET Fest 2019. Kevin Dockx. Uncovering Swagger/OpenAPI Slide 14 .NET Fest 2019. Kevin Dockx. Uncovering Swagger/OpenAPI Slide 15 .NET Fest 2019. Kevin Dockx. Uncovering Swagger/OpenAPI Slide 16 .NET Fest 2019. Kevin Dockx. Uncovering Swagger/OpenAPI Slide 17 .NET Fest 2019. Kevin Dockx. Uncovering Swagger/OpenAPI Slide 18 .NET Fest 2019. Kevin Dockx. Uncovering Swagger/OpenAPI Slide 19 .NET Fest 2019. Kevin Dockx. Uncovering Swagger/OpenAPI Slide 20 .NET Fest 2019. Kevin Dockx. Uncovering Swagger/OpenAPI Slide 21 .NET Fest 2019. Kevin Dockx. Uncovering Swagger/OpenAPI Slide 22 .NET Fest 2019. Kevin Dockx. Uncovering Swagger/OpenAPI Slide 23 .NET Fest 2019. Kevin Dockx. Uncovering Swagger/OpenAPI Slide 24 .NET Fest 2019. Kevin Dockx. Uncovering Swagger/OpenAPI Slide 25 .NET Fest 2019. Kevin Dockx. Uncovering Swagger/OpenAPI Slide 26 .NET Fest 2019. Kevin Dockx. Uncovering Swagger/OpenAPI Slide 27 .NET Fest 2019. Kevin Dockx. Uncovering Swagger/OpenAPI Slide 28 .NET Fest 2019. Kevin Dockx. Uncovering Swagger/OpenAPI Slide 29 .NET Fest 2019. Kevin Dockx. Uncovering Swagger/OpenAPI Slide 30
Upcoming SlideShare
What to Upload to SlideShare
Next

1 Like

Share

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

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

Related Audiobooks

Free with a 30 day trial from Scribd

See all

.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
  • MichellePalma19

    Nov. 28, 2021

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

Views

Total views

225

On Slideshare

0

From embeds

0

Number of embeds

0

Actions

Downloads

0

Shares

0

Comments

0

Likes

1

×