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

1. KEVINDOCKX
https://www.kevindockx.com
UNCOVERING
SWAGGER/
OPENAPI
In this session, you’ll learn all
about documenting your API with
OpenAPI (Swagger)

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. 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. 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. 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. KEVINDOCKX
MARVIN
OPENAPI COMPONENTS AND TOOLS

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. 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. 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. 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. KEVINDOCKX
MARVIN
Standards-based
development allows you to
mix and match components
based on that standard
11

12. KEVINDOCKX
MARVIN
DEMO TIME Time to dive into code
12

13. KEVINDOCKX
MARVIN
Design your contract first.
Implement it later.
I like paper. But creating
the contract with OpenAPI
is probably better.
13

14. KEVINDOCKX
MARVIN
ApiExplorer is an
abstraction on top of
ASP.NET Core MVC that
exposes metadata about
that application
14

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. 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. KEVINDOCKX
MARVIN
DEMO TIME Time to dive into code
17

18. KEVINDOCKX
MARVIN
ANALYZERS TO THE RESCUE
18
Analyzers analyse your code and help improving it
Microsoft.AspNetCore.Mvc.Api.Analyzers

19. KEVINDOCKX
MARVIN
DEMO TIME Time to dive into code
19

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. KEVINDOCKX
MARVIN
Content negotiation is the
mechanism used for serving
different representations of
a resource at
the same URI
21

22. KEVINDOCKX
MARVIN
CONTENT NEGOTIATION
GET api/movies/{id}
{ movie in JSON}
{ movie in XML}
movie

23. KEVINDOCKX
MARVIN
CONTENT NEGOTIATION
GET api/movies/{id}
{ movie in JSON}
movie
Accept: application/json

24. KEVINDOCKX
MARVIN
CONTENT NEGOTIATION
GET api/movies/{id}
{ movie in XML}
movie
Accept: application/xml

25. KEVINDOCKX
MARVIN
“application/json” tells us
something about the format
of the representation, but
nothing about the actual
type
25

26. KEVINDOCKX
MARVIN
ADVANCED CONTENT NEGOTIATION
GET api/movies/{id}
movie
{
"authorFirstName": "Stephen",
"authorLastName ": "King",
…
}
{
"author": "Stephen King",
…
}
application/json?
application/json?

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. 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. 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. THANK YOU