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

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
OpenAPI3.0, And What It Means for the
Future of Swagger

2. 2
Today’s Presenters
Ole Lensmar
CTO, SmartBear Software
Chair, OpenAPIInitiative
Ron Ratovsky
Swagger Developer Evangelist, SmartBear
Software
Member, OpenAPITechnical 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
•OpenAPIInitiative Overview
•Why OAS 3.0 became thestandard
•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
OpenAPIInitiative Overview

6. 6
History of OpenAPIInitiative
•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
•OpenAPIInitiative reaches 27 members,
including software providers and industry
leaders in banking, healthcare, finance, & tech
•OpenAPI3.0 officially released on 7/26

7. 7
The OpenAPIInitiative
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 useopen source governance best practices, including license and
contribution agreement choices, in keeping with the ideals of Linux.

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

9. 9
What isthe OpenAPISpecification?
A common, public contractbetween 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 OpenAPI3.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 commonand 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
OpenAPI2.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 OpenAPILinks
OpenAPILinks 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
-CommonMarksupport 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 securityDefinitionsall moved
under components
2.schemes, host, basePathhave been replaced by servers
3.Parameters need to be restructured:
-Type definitions move under schema
-Body and formDataparameters extracted to a requestBody
4.Responses need to be restructred:
-‘produces’mediatypes 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 –60kAPI
developers, architects, devops, technical
writers, & managers use SwaggerHubto
design & document APIs

34. 34
Built for OpenAPISpecification
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
SwaggerHubis 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 SwaggerHubfor Free
www.swaggerhub.com