This document discusses the evolution of the OpenAPI Specification (formerly known as the Swagger specification) and the formation of the Open API Initiative. It provides an overview of the OpenAPI Specification and how it offers a standard way to define REST APIs. It also outlines how the specification has been adopted broadly and the importance of having a common definition for REST APIs.

1. The Swagger Format becomes the Open API
Specification: Standardizing descriptions of Web
APIs for interoperability
Steven Willmott
CEO, 3scale Inc.
steve@3scale.net : @njyx

2. Credits
2
▪ Slides from Marsh Gardiner (Apigee), Dennis Brenan
(Capital One), Tony Tam (Smartbear), Ole Lensmar
(Smartbear) and myself
▪ http://openapis.org/

3. Who Am I?
▪ http://www.3scale.net
▪ @3scale
▪ Early Swagger supporter
▪ Now OAI Founding Member
3
▪ CEO of 3scale
▪ Leading API Infrastructure Provider
▪ 700+ Customers
▪ Billions of API Calls Managed

4. Introduction & Agenda
4
▪ OpenAPI Specification (OAS)
▪ Open API Initiative (OAI)
▪ Usage and Tooling Examples

5. The OpenAPI Specification
fka “the Swagger specification”
DRAFT - Open API Initiative (OAI) 5

6. What is the OpenAPI Specification?
6
Generally Categorized
REST API Description Language
More Generally
IDL for REST APIs

7. What does the OpenAPI Specification Offer?
7
A simple format for writing REST service contracts
▪ Are independent from language, development framework,
deployment technology
▪ Can be expressed in YAML or JSON format
▪ Support both API-first and code-first approaches to
defining, building and documenting APIs
▪ Have a clean & powerful extension mechanism
Language
Neutral
& Machine
Readable Format
APIs can be
defined in JSON
or YAML
API-First &
Code-First
Development
Powerful
Extension
Mechanism
Comprehensive Tooling Support (core, UI, codegen, editor)

8. Road to the OAS
8
2010
Tony Tam @Wordnik founded Swagger
Q1 2015
Swagger acquired by SmartBear
Q3 2015
Linux Foundation Workgroup Forms
Q4 2015
Swagger renamed “OpenAPI Specification”
2010 - 2014
Development, Growth, Adoption, Tooling, Community

9. Adoption & Growth
9
▪ 100,000 weekly source visits
▪ 11,500 daily downloads
▪ 10,000 daily visitors to swagger.io
▪ 4,600 forks of official repos
▪ 1,700 public repos on GitHub
▪ Client/server support in all popular
languages & frameworks
Most Popular API Framework

10. Community
10 December 2014DRAFT - Open API Initiative 10

11. Broad Industry Adoption
11

12. Why adopt the OpenAPI Specification?
12
Commitment to Remain
Open
Portable
Vendor Neutral
Strong Independent
Sponsorship
CommunitySimple & Pragmatic
Superior Tooling Best Industry Support

13. The Importance of API Interface
Definitions
13

14. 14
What about Rest Interfaces?

15. 15
What Spec? Spec Generates
Code
Spec as
Code
Code is
Spec
REST API Development Evolution

16. Shared Definitions are Crucial
▪ Stable Interface Definition
▪ Managed process around
change
▪ Discovery of capabilities
▪ Automation of processes and
procedures
▪ Essential at 100’s APIs
▪ Invaluable at 10’s Thousands
and Millions
16Photo: Josh Hibbert / Unsplash.com
In your organization: inter-team
dependencies
Across the public Internet: cross-
organization discovery & contracts

17. Shared Definitions are Crucial
▪ Fixed point of Reference
▪ Automation:
▪ Explorers / Docs
▪ Code Gen
▪ Editors
▪ Search
▪ Testing
▪ Change Management
▪ Management platforms
▪ Design Focus
17

18. The Open API Initiative
18

19. The Open API Initiative - Mission
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 OpenAPI Specification.
19

20. OAI Initial Steps
▪ Establishment of a clear, open governance structure for both
business & technical direction
▪Swagger specification donated to the Open API Initiative
▪ Meritocratic approach to technical contributions – not pay-to-play
▪ Charter is here: https://openapis.org/governance
20

21. OAI Governance Structure
21
Business
Governance
Board
(BGB)
Budget, marketing,
community, etc…
Technical
Developer
Community
(TDC)
Manages the
OpenAPI
Specification
Technical
Oversight
Board
(TOB)
Resolves conflict in
TDC

22. Swagger ➔ OpenAPI Specification (OAS)
▪ Moved from swagger-api 2.0 to OAI GitHub Repository
▪ https://github.com/oai/OpenAPI-Specification
▪ Core TDC elected and working on next version 3.0 of spec
▪ Apache 2.0 License as before
▪ You can/should join the discussion – please do!
22

23. Focus of OpenAPI Spec 3.0
Aiming for 2016 summer release ~mid July
23
Documentatio
n
Structure
Protocols and
Payloads
JSON Schema
& JSON
References
URI Support
Error
Handling/Docu
mentation
Security
Request
Parameters

24. 24
OAS Usage Examples

25. 25
Code First with Swagger Annotations

26. 26
Swagger UI
Build docs by
processing
JSON/YAML API
Spec
The API Spec can be
returned from static
source or from the
running API

27. 27
API First with Swagger Editor
Wrapped Swagger
Editor
Lifecycle Tooling
Manage API
Metadata
Governance &
Review
Dynamic Mock
Responses

28. And Finally…
28

29. Get Involved!
Website: https://openapis.org/
Spec: https://github.com/oai
Follow: @OpenApiSpec
29

30. Additional Information
30

31. 31
OpenAPI Spec’s X-Extensions
Additional data added to API definition
to extend the specification
Always prefixed by "x-" and can have
any valid JSON/YAML format value

32. 32
OpenAPI Spec’s X-Extensions
paths:
/demo/bankthings:
get:
summary: Returns a list of Bank Things
operationId: getBankThings
x-c1-proxy: audit
parameters:
- $ref: '#/parameters/ApiKey'

33. 33
From Legacy Java Framework to
Polyglot Microservices using OpenAPI
@Annotations & Servlet Filters ➔ X-Extensions