Slide 1
Slide 1 text
The OpenAPI Specification 3.0
… the next generation
Ron Ratovsky, @webron
SmartBear
March 9, 2017
Slide 2
Slide 2 text
CommonMark in, GFM out
GFM
Slide 3
Slide 3 text
Structural Improvements
OpenAPI 2.0
info
host
paths
parameters
security
tags externalDocs
basePath
schemes securityDefinitions
responses
definitions
produces consumes
OpenAPI 3.0
info
servers
paths
components
security
tags externalDocs
Slide 4
Slide 4 text
Introducing Servers
• Replaces schemes, host, basePath
• Allows definition of multiple servers
• Variable substitution support
• Defined at top, path or operation
level
servers:
- url: https://{user}.big-
server.com:{port}/{path}
description: The production API server
variables:
user:
default: demo
port:
enum:
- 8443
- 443
default: 8443
path:
default: v2
Slide 5
Slide 5 text
Extended Reusability
• All under one roof
• Standardized naming
• Added new objects
OpenAPI 3.0
Components
schemas
responses
parameters
examples
requestBodies
headers
securitySchemes
links
callbacks
Slide 6
Slide 6 text
Path Item Changes
• Description
• New TRACE support
• Override Servers
• No support for payloads for GET, DELETE…
Slide 7
Slide 7 text
Parameters Overview
Slide 8
Slide 8 text
Request Body & Content
• Specify different Media Types
• Supports reusability
• Provide examples
• Replaces formData parameters
• Improved file upload handling
Slide 9
Slide 9 text
Parameters
Parameter
name
in
description
required
deprecated
allowEmptyValue
style
explode
allowReserved
schema
example
examples
content
Slide 10
Slide 10 text
Responses
• Wildcard response codes
• Response headers can be complex types too
• Content for payload
• Introducing: Links
Slide 11
Slide 11 text
Links
Slide 12
Slide 12 text
Callbacks
myWebhook:
'$request.body#/url':
post:
requestBody:
description: Callback payload
content:
'application/json’:
schema:
$ref: '#/components/schemas/SomePayload'
responses:
200:
description: webhook successfully processed an no retries will be performed
Slide 13
Slide 13 text
JSON Schema
• Updated support to latest Wright Draft 00 (Draft 05)
• Added support for onyOf, anyOf, not
• nullable, deprecated, writeOnly
• Clarified JSON References
• Clarified other restrictions
Slide 14
Slide 14 text
Security Definitions
• OAuth2 flow names finally make sense
• Multiple flow support
• Introduced support for OpenID Connect
• Replaced `basic` with `http` and…
• Added `scheme` and `bearerFormat`
Slide 15
Slide 15 text
Get Involved! Follow @OpenApiSpec
Blog series on spec changes:
bit.ly/openapi3changes
OAI Website:
openapis.org
On GitHub (see the OpenAPI.Next branch):
https://github.com/OAI