OpenAPI 3.0, which is based on the original Swagger 2.0 specification, is meant to provide a standard format to unify how an industry defines and describes RESTful APIs. The release of OAS 3.0 marks a significant milestone in the growth of the API economy — bringing together collaborators from across industries, to evolve the specification to meet the needs of API developers and consumers across the world in an open and transparent manner. We hosted a free Swagger training: OpenAPI 3.0, And What it Means for the Future of Swagger. More than 2,000 people signed up to learn more about the new specification, and to find out about what’s coming next for Swagger and SwaggerHub! You can watch the full recording of the presentation here: https://swaggerhub.com/blog/api-resources/openapi-3-0-video-tutorial/

1. 1
OpenAPI 3.0, And What It Means for the
Future of Swagger

2. 2
Today’s Presenters
Ole Lensmar
CTO, SmartBear Software
Chair, OpenAPI Initiative
Ron Ratovsky
Swagger Developer Evangelist, SmartBear
Software
Member, OpenAPI Technical Development
Community

3. 3
Today’s Webinar Presented by SmartBear Software
PLANNING DESIGN IMPLEMENT + TEST DEPLOY RETIRE
eBOOKS
WORKSHOPS
DESIGN
DOCUMENT
CODE
INTEGRATE
FUNCTIONAL
PERFORMANCE
SECURITY
VIRTUALIZATION
MONITOR
DEPLOY
DEPRECATE
VERSION
TRAININGS
CONFERENCES
PARTNER INTEGRATIONS
OPEN SOURCE
OFFERINGS
COMMERCIAL
OFFERINGS

4. 4
Today’s Agenda
• OpenAPI Initiative Overview
• Why OAS 3.0 became the standard
• What’s new in OAS 3.0
• OAS 3.0 in the API Lifecycle
• What’s next for Swagger & SwaggerHub
• Live Swagger demo
• Q&A

5. 55
OpenAPI Initiative Overview

6. 6
History of OpenAPI Initiative
• Swagger Project founded in 2010 by Tony
Tam / Reverb to design and document API
interfaces
• Groups large & small drawn to Project
Interested in its simplicity, pragmatic
approach, potential open governance
• Acquired by SmartBear in early 2015
• Swagger 2.0 Spec donated by SmartBear
Software to the Open API Initiative
• OpenAPI Initiative reaches 27 members,
including software providers and industry
leaders in banking, healthcare, finance, & tech
• OpenAPI 3.0 officially released on 7/26

7. 7
The OpenAPI Initiative
Provide an open source, technical community, within which industry
participants may easily contribute to building a vendor-neutral, portable and
open specification for providing technical metadata for REST APIs
The OAI is a collaborative project under the guidance of the The Linux Foundation.
LF Projects use open source governance best practices, including license and
contribution agreement choices, in keeping with the ideals of Linux.

8. 8
The OpenAPI Initiative - 2 main bodies
• BGB - Provides governance for the OpenAPI Spec
• Evangelization / Events / Sponsorships
• Drives the APIStrat conference (new!)
• Expertise & Knowledge Sharing
• Licensing / Legal / Trademarks
• Does not have any influence on the technical direction of the spec
• TDC – Drives the evolution of the OpenAPI Spec
• Drives the technical direction of the specification
• Managed like any open-source project at https://github.com/OAI
• Anyone is welcome and encouraged to join and suggest, discuss, ask
and complain!

9. 9
What is the OpenAPI Specification?
A common, public contract between services
Independent of language, framework,
deployment technology
YAML or JSON format
Supports both API-first and code-first
approaches to defining, building and
documenting APIs
Bottom-up community and usage driven
evolution

10. 10
Swagger? OpenAPI? OAS? OAI?
Specification
Tools

11. 1111
What’s New in OpenAPI 3.0?

12. 12
OAS 3.0 Specification Change Criteria
• Clarity - The current "way" something is done doesn't make sense, is complicated, or not
clear
• Consistency - A portion of the specification is not consistent with the rest, or the industry
standard terminology
• Necessary functionality - We are missing functionality because of a certain design of the
specification
• Forward-looking designs - As usage of APIs evolves to new protocols, formats,
patterns, we should always be considering what the next important functionality should be
• Impact - A change will provide impact on a large number of use cases. We should not be
forced to accommodate every use case. We should strive to make the common and important
use cases both well supported and common in the definition of the OAI Spec.

13. 13
So, What’s New in OAS 3.0?
✓ Improved reusability
✓ Parameter changes
✓ Content negotiation support
✓ Support for describing callbacks
✓ Links to express relationships between operations
✓ Improved examples
✓ Enhanced security definitions

14. 14
Specification Restructure and Improve Reusability
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

15. 15
Specification Restructured and Improve Reusability
OpenAPI 3.0
Components
schemas
responses
parameters
examples
requestBodies
headers
securitySchemes
links
callbacks
- All reusable components are under
one roof
- Standardized naming
- Added new objects for extended
reusability

16. 16
So, What’s New in OAS 3.0?
✓ Improved reusability
✓ Parameter changes
✓ Content negotiation support
✓ Support for describing callbacks
✓ Links to express relationships between operations
✓ Improved examples
✓ Enhanced security definitions

17. 17
Improved parameter descriptions
- New parameter type: cookie
- Remove parameter types: body,
formData
- All parameters support complex
types
- Further serialization support by
defining media types

18. 18
So, What’s New in OAS 3.0?
✓ Improved reusability
✓ Parameter changes
✓ Content negotiation support
✓ Support for describing callbacks
✓ Links to express relationships between operations
✓ Improved examples
✓ Enhanced security definitions

19. 19
Content Negotiation Support
- Requests bodies and
responses allow defining
different schemas and
examples for different media
types
- Improved file upload support
- Responses support wildcard
code definition
- Eliminates `consumes` and
`produces` from the spec

20. 20
So, What’s New in OAS 3.0?
✓ Improved reusability
✓ Parameter changes
✓ Content negotiation support
✓ Support for describing callbacks
✓ Links to express relationships between operations
✓ Improved examples
✓ Enhanced security definitions

21. 21
Support for Describing Callbacks
- Allows definition of async
APIs
- Callbacks need to be
implemented by both clients
and servers
- Callback URLs are
expression based
- Callbacks are defined by
using the same structure as
other path definitions

22. 22
So, What’s New in OAS 3.0?
✓ Improved reusability
✓ Parameter changes
✓ Content negotiation support
✓ Support for describing callbacks
✓ Links to express relationships between
operations
✓ Improved examples
✓ Enhanced security definitions

23. 23
Introducing OpenAPI Links
OpenAPI Links are Client-Computed, Design-Time Parameterized
Traversals between Responses and Operations
- Creation relations between responses and
other operations
- Parameters can depend on both the request
and response
- Client can follow links automatically
- Depends on the API definition alone without
runtime impact

24. 24
So, What’s New in OAS 3.0?
✓ Improved reusability
✓ Parameter changes
✓ Content negotiation support
✓ Support for describing callbacks
✓ Links to express relationships between operations
✓ Improved examples
✓ Enhanced security definitions

25. 25
Enhanced Examples
- Examples can live in
Parameters, Request Bodies,
Responses and Schemas (*)
- Examples can be reused
- Additional Metadata
- Name
- Description
- Can reference an external
example

26. 26
So, What’s New in OAS 3.0?
✓ Improved reusability
✓ Parameter changes
✓ Content negotiation support
✓ Support for describing callbacks
✓ Links to express relationships between operations
✓ Improved examples
✓ Enhanced security definitions

27. 27
Enhanced Security Definitions
- Renamed OAuth2 flows
- Support for multiple flows
- OpenID Connect support
- ‘basic’ was replaced by ‘http’
- Supports different schemes
and bearer formats

28. 28
OAS 3.0 – Additional Changes
- CommonMark support in descriptions
- Extended JSON Schema support
- Multiple and templated server definitions
- Support for TRACE method
- No payload support for DELETE, GET…

29. 29
3.0 is a complete breaking change from 2.0
1. definitions, parameters, responses and securityDefinitions all moved
under components
2. schemes, host, basePath have been replaced by servers
3. Parameters need to be restructured:
- Type definitions move under schema
- Body and formData parameters extracted to a requestBody
4. Responses need to be restructred:
- ‘produces’media types moved to this level
5. Some security definition changes:
- `basic` changed to `http`
- OAuth2 flows renamed, given a slightly different structure

30. 3030
OAS 3.0 in the API Lifecycle

31. 31
Driving the API Lifecycle with OAS
Design
Implementation
Testing
Mocking
Documentation
Virtualization
Deployment /
Runtime
Clients
Security, Usage policies,
Monitoring, Caching, etc
Developer portals,
Code samples, User guides, etc.
Functional / Runtime simulations
Functional, Security,
Load, Compliance, etc.
Generated server code/artifacts
Prototyping
Generated client libraries
Object reuse, linking,
Callbacks, etc.

32. 3232
What’s Next for Swagger?

33. 33
Swagger: The World’s Most Popular API Tooling for OpenAPI
• 10 Million Downloads Worldwide
• Combination of Swagger UI and Swagger
Editor downloaded once every 3
seconds
• SwaggerHub, launched 2015 – 60k API
developers, architects, devops, technical
writers, & managers use SwaggerHub to
design & document APIs

34. 34
Built for OpenAPI Specification
Swagger Editor Swagger UI Swagger Codegen
HTML, Javascript, and CSS
assets that dynamically
generate documentation
The first open source
editor fully dedicated
to OAS-based APIs.
Turn your OAS definition
into code, generating
server stubs & client SDKs

35. 35
SwaggerHub: API Design & Documentation Platform
SwaggerHub is an integrated API design and documentation platform, built for
teams to drive consistency and discipline across the API development workflow.

36. 36
Timeline of OAS 3.0 Support
AUGUST
• Swagger-UI/Editor
✓Editing/Viewing – out now!
▪ Sandbox functionality – end of August
• Swagger-JS – end of August
• Swagger-Core – mid August
• Swagger-Parser – mid August
• Swagger-Converter – end of August
• Swagger-Inflector – end of August
SEPTEMBER
• Swagger-Validator – mid September
• Swagger-Codegen – end of
September
• SwaggerHub – mid September

37. 3737
Let’s See It in Action

38. 38
Next Steps
Additional Resources
Swagger.io/docs/specification
Learn Try Connect
GitHub
SwaggerAPI
Twitter
@SwaggerAPI
Subscribe
swagger.io/blog

39. 39
The Platform for Designing and Documenting
APIs with Swagger
Try SwaggerHub for Free
www.swaggerhub.com