The document provides an overview of the Open API Initiative and the Open API Specification (OAS), highlighting its purpose as a vendor-neutral and portable standard for defining REST APIs. It details the evolution of OAS, its community-driven governance structure, and the advantages of adopting this specification for API development. The document also emphasizes the benefits of OAS including comprehensive tooling support and the ability to generate code from API specifications.

1. Open API Initiative
Dennis Brennan
Director of Engineering
Capital One

2. Introduction & Agenda
2
▪ Open API Specification (OAS)
▪ Open API Initiative (OAI)
▪ Using OAS in the Enterprise

3. The Open API Specification
fka The Swagger Specification
10 December 2014DRAFT - Linux Foundation Confidential 3

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

5. What does the OpenAPI Specification Offer?
5
A simple format for creating 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)

6. Road To the OAS
6
2010
Tony Tam @Reverb 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

7. Adoption & Growth
7
▪ 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

8. Community
10 December 2014DRAFT - Linux Foundation Confidential 8

9. Broad Industry Adoption
9

10. Why adopt the OpenAPI Specification?
10 December 2014DRAFT - Linux Foundation Confidential 10
Commitment to Remain
Open
Portable
Vendor Neutral
Strong Independent
Sponsorship
CommunitySimple & Pragmatic
Superior Tooling Best Industry Support

11. The Open API Initiative
10 December 2014DRAFT - Linux Foundation Confidential 11

12. 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.
12

13. OAI initial steps
▪ Swagger Specification donated to the Workgroup
▪ Establishment of a clear, open governance structure for both
business & technical direction
▪ Meritocratic approach to technical contributions – not pay-to-play
▪ Charter is here: https://openapis.org/governance
20 August 2015 13Linux Foundation Confidential

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

15. 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
▪ Anyone can join the discussion – please do!
15

16. Focus of OpenAPI Spec 3.0
Aiming for 2016 summer release ~June
16
Documentation
Structure
Protocols and
Payloads
JSON Schema
& JSON
References
URI Support
Error
Handling/Docu
mentation
Security
Request
Parameters

17. 17
Using OAS in the Enterprise

18. 20 August 2015 18Linux Foundation Confidential
What Spec? Spec Generates
Code
Spec as
Code
Code is
Spec
REST API Development Evolution

19. 19
What Spec?
Let’s just
code!

20. 20
What about Rest Interfaces?
2010s

21. 21
Let’s put the
docs in the
code.
Code is Spec

22. 22
Code First with Swagger Annotations

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

24. 24
Let’s start
with the API
Spec!
Spec Generates Code

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

26. 26
Iterative Codegen Process

27. 27
Let’s Code…
a lot less!
Spec as Code

28. Behavior in API Driven Directly from Spec
Reduces Code Generation & Plumbing
▪ Swagger Inflector: Wires API spec to server with programmatic
endpoint generation.
▪ Apigee-127: Message validation, OAuth, quota, caching, and
other services are all handled through the metadata in your
Swagger spec (e.g. OAS Vendor Extensions)
28
Examples

29. 29
OAS Vendor Extensions
Additional data added to API definition
to extend the specification
Always prefixed by "x-" and can have
any valid JSON format value

30. 30
OAS Vendor Extensions
paths:
/demo/bankthings:
get:
summary: Returns a list of Bank Things
operationId: getBankThings
x-c1-proxy: audit
parameters:
- $ref: '#/parameters/ApiKey'

31. 31
From Legacy Java Framework to
Polyglot Microservices with the OAS
@Annotations & Servlet Filters ➔ OAS Vendor Extensions

32. 32
Pre/Post Processing
based on Servlet Filters
& Annotations
Single Language &
Development
Framework
Binary Dependencies for
Processing Services

33. 33
Pre/Post processing
moves to local proxy
(Smart Gateway)
Behavior notated in the
API spec with vendor
extensions
Enables more options to
build simple APIs
(Dumb API)
Infrastructure &
Services instead of
binary dependencies

34. And Finally…
34

35. Get Involved!
▪ https://openapis.org/
▪ https://github.com/oai
▪ @OpenApiSpec
35