INTERFACE, by apidays - APIs: the next 10 years June 8, 9 & 10 2022 OpenAPI 3 does what Swagger 2.0 doesn't Arnaud Lauret, The API Handyman & Author of the "Design of Web APIs", OpenAPI Lead at Postman ------------ Check out our conferences at https://www.apidays.global/ Do you want to sponsor or talk at one of our conferences? https://apidays.typeform.com/to/ILJeAaV8 Learn more on APIscene, the global media made by the community for the community: https://www.apiscene.io Explore the API ecosystem with the API Landscape: https://apilandscape.apiscene.io/ Deep dive into the API industry with our reports: https://www.apidays.global/industry-reports/ Subscribe to our global newsletter: https://apidays.typeform.com/to/i1MPEW

1. @APIHANDYMAN POSTMAN OPEN TECHNOLOGIES
OPENAPI DOES WHAT SWAGGER DON’T
IMPROVED STRUCTURE: IMPROVED SECURITY:
IMPROVED HOSTING:
IMPROVED CONTRACT: IMPROVED DOCUMENTATION:
Altered Specification The Revenge of Consistency Mortal Servers Streets of Security II
Data Force IV After Event II Phantasy Examples II Shining Documentation

2. 2022 SERIES OF EVENTS
New York
JULY
(HYBRID)
Australia
SEPTEMBER
(HYBRID)
Singapore
APRIL
(VIRTUAL)
Helsinki & North
MARCH
(VIRTUAL)
Paris
DECEMBER
(HYBRID)
London
OCTOBER
(HYBRID)
Hong Kong
AUGUST
(VIRTUAL)
JUNE (VIRTUAL)
India
MAY
(VIRTUAL)
APRIL (VIRTUAL)
Dubai & Middle East
JUNE
(VIRTUAL)
Check out our API Conferences
www.a pida ys .globa l
Want to talk at one of our conferences?
apidays.typeform.com/to/ILJeAaV8

3. @APIHANDYMAN POSTMAN OPEN TECHNOLOGIES
API Handyman does what Arnaud Lauret does
ME: MY COMPANY:
MY BOOK:
Arnaud Lauret @apihandyman Postman Open Technologies
The Design of Web APIs Web APIの設計 웹 API 디자인 ПРОЕКТИРОВАНИЕ ВЕБ-AP

4. @APIHANDYMAN POSTMAN OPEN TECHNOLOGIES
The reference: Sega vs Nintendo 90s rivalry

5. @APIHANDYMAN POSTMAN OPEN TECHNOLOGIES
Previously in the APIverse

6. @APIHANDYMAN POSTMAN OPEN TECHNOLOGIES
It’s not Swagger vs OpenAPI

7. @APIHANDYMAN POSTMAN OPEN TECHNOLOGIES
It’s Swagger then OpenAPI

8. @APIHANDYMAN POSTMAN OPEN TECHNOLOGIES
2 versions of OpenAPI 3

9. @APIHANDYMAN POSTMAN OPEN TECHNOLOGIES
OPENAPI 3 IMPROVES SWAGGER 2
IMPROVED STRUCTURE: IMPROVED SECURITY:
IMPROVED HOSTING:
IMPROVED CONTRACT: IMPROVED DOCUMENTATION:
Altered Specification The Revenge of Consistency Mortal Servers Streets of Security II
Data Force IV After Event II Phantasy Examples II Shining Documentation

10. @APIHANDYMAN POSTMAN OPEN TECHNOLOGIES
swagger: “2.0”
Altered Specification (version)
openapi: “3.0.3”

11. @APIHANDYMAN POSTMAN OPEN TECHNOLOGIES
Altered Specification (reusable components)
swagger: “2.0”
info: …
paths: …
definitions: …
parameters: …
openapi: “3.0.3”
info: …
paths: …
components:
schemas: …
parameters: …

12. @APIHANDYMAN POSTMAN OPEN TECHNOLOGIES
The Revenge of Consistency (all data defined the same way)
swagger: “2.0”
paths:
/resources/{resourceId}:
parameters:
- name: resourceId
type: string
definitions:
# Only for bodies
openapi: “3.0.3”
paths:
/resources/{resourceId}:
parameters:
- name: resourceId
schema:
$ref: …/schemas/id
components:
schemas:
# For all data

13. @APIHANDYMAN POSTMAN OPEN TECHNOLOGIES
The Revenge of Consistency (more reusable components)
swagger: “2.0”
definitions: …
parameters: …
responses: …
securityDefinitions: …
openapi: “3.0.3”
components:
schemas: …
parameters: …
requestBodies: …
responses: …
securitySchemes: …
examples: …
headers: …

14. @APIHANDYMAN POSTMAN OPEN TECHNOLOGIES
Mortal Servers (multiple servers)
swagger: “2.0”
schemes:
- https
host: server.com
basePath: /name/v1
openapi: “3.0.3”
servers:
- description: production
url:
https://server.com/name/v1
- description: mock
url:
https://mock.com/name/v1

15. @APIHANDYMAN POSTMAN OPEN TECHNOLOGIES
Mortal Servers (server variables)
openapi: “3.0.3”
servers:
- description: production
url:
https://server.com/name/v1
- description: mock
url:
https://mock.com/name/v1
openapi: “3.0.3”
servers:
- description: production
url:
https://{type}.com/name/v1
variables:
type:
enum:
- server
- mock

16. @APIHANDYMAN POSTMAN OPEN TECHNOLOGIES
Streets of Security II (enhanced and new security modes)
swagger: “2.0”
securityDefinitions:
# Basic Authentication
# API Key
# Oauth2
openapi: “3.x.x”
components:
securitySchemes:
# HTTP (Basic, Bearer)
# API Key
# Oauth 2 (fixed)
# OpenId Connect
# Mutual TLS (3.1)

17. @APIHANDYMAN POSTMAN OPEN TECHNOLOGIES
Data Force IV (more versatile schemas)
swagger: “2.0”
definitions:
# JSON Schema Draft 4 (mod)
openapi: “3.0.3”
components:
schemas:
# JSON Schema Draft 5 (mod)
# Notable enhancements
# oneOf, anyOf, not
# writeOnly

18. @APIHANDYMAN POSTMAN OPEN TECHNOLOGIES
Data Force IV (choose your JSON Schema)
swagger: “2.0”
definitions:
# JSON Schema Draft 4 (mod)
openapi: “3.1.0”
components:
schemas:
# Default: JSON Schema
# Draft 2020-12
# Overridden by $schema

19. @APIHANDYMAN POSTMAN OPEN TECHNOLOGIES
Data Force IV (enhanced content negotiation)
swagger: “2.0”
# 1 schema for all media types
paths:
/resources:
get:
produces:
- application/json
- text/csv
responses:
200:
schema:
openapi: “3.0.3”
# Specific schemas for each
paths:
/resources:
get:
responses:
200:
content:
application/json:
schema: …
text/csv:
schema: …

20. @APIHANDYMAN POSTMAN OPEN TECHNOLOGIES
Data Force IV (enhanced parameter/header serialization)
swagger: “2.0”
parameters:
aParameter:
type: array
collectionFormat: …
openapi: “3.0.3”
components:
parameters:
aParameter:
# array or object
style: …
explode: …

21. @APIHANDYMAN POSTMAN OPEN TECHNOLOGIES
After Event II (webhooks & callbacks)
swagger: “2.0” openapi: “3.x.x”
paths:
/resources:
post:
callbacks: # 3.0
webhooks: # 3.1
/events:
post: …

22. @APIHANDYMAN POSTMAN OPEN TECHNOLOGIES
Phantasy Examples II (multiple examples)
swagger: “2.0”
# Example only on bodies
example:
# single undocumented
# example
openapi: “3.0.3”
# Examples on bodies,
# parameters, headers
examples:
anExample:
summary: …
description: …
value: …
# or
externalValue: …

23. @APIHANDYMAN POSTMAN OPEN TECHNOLOGIES
Shining Documentation (more summaries and descriptions)
swagger: “2.0”
info:
description: …
paths:
/resources:
openapi: “3.1.0”
info:
summary: …
description: …
paths:
/resources:
summary: …
description: …

24. @APIHANDYMAN POSTMAN OPEN TECHNOLOGIES
Thank you and goodbye Swagger 2
USE OPENAPI 3 NOW AND
GET ALL OF ITS EXCLUSIVE
NEW FEATURES FREE.

25. @APIHANDYMAN POSTMAN OPEN TECHNOLOGIES
The path to OpenAPI 3 upgrade
USE OPENAPI 3 NOW AND
GET ALL OF ITS EXCLUSIVE
NEW FEATURES FREE (almost).

26. @APIHANDYMAN POSTMAN OPEN TECHNOLOGIES
The path to OpenAPI 3 upgrade
Upgrade
your tools
Check third
party tools
compatibility
Convert existing
documents

27. @APIHANDYMAN POSTMAN OPEN TECHNOLOGIES