The Swagger Format becomes the Open API Specification ...
Transcript of The Swagger Format becomes the Open API Specification ...
The Swagger Format becomes the Open API Specification: Standardizing descriptions of Web APIs for interoperability
Steven WillmottCEO, 3scale Inc.
[email protected] : @njyx
Credits
2
▪ Slides from Marsh Gardiner (Apigee), Dennis Brenan (Capital One), Tony Tam (Smartbear), Ole Lensmar(Smartbear) and myself
▪ http://openapis.org/
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
Introduction & Agenda
4
▪ OpenAPI Specification (OAS)▪ Open API Initiative (OAI)▪ Usage and Tooling Examples
The OpenAPI Specificationfka “the Swagger specification”
DRAFT - Open API Initiative (OAI) 5
What is the OpenAPI Specification?
6
Generally CategorizedREST API Description Language
More GenerallyIDL for REST APIs
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
LanguageNeutral
&MachineReadableFormat
APIscanbedefinedinJSON
orYAML
API-First&Code-First
Development
PowerfulExtensionMechanism
ComprehensiveToolingSupport(core,UI,codegen,editor)
Road to the OAS
8
2010Tony Tam @Wordnik founded Swagger
Q1 2015Swagger acquired by SmartBear
Q3 2015 Linux Foundation Workgroup Forms
Q4 2015 Swagger renamed “OpenAPI Specification”
2010 - 2014Development, Growth, Adoption, Tooling, Community
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
MostPopularAPIFramework
Community
10 December 2014DRAFT - Open API Initiative 10
Broad Industry Adoption
11
Why adopt the OpenAPI Specification?
12
CommitmenttoRemain
OpenPortable
VendorNeutral
StrongIndependentSponsorship
CommunitySimple&Pragmatic
SuperiorTooling BestIndustrySupport
The Importance of API Interface Definitions
13
14
What about Rest Interfaces?
15
What Spec? Spec Generates Code
Spec as Code
Code is Spec
REST API Development Evolution
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
Inyourorganization:inter-teamdependencies
AcrossthepublicInternet:cross-organizationdiscovery&contracts
Shared Definitions are Crucial
▪ Fixed point of Reference▪ Automation:
▪ Explorers / Docs▪ Code Gen ▪ Editors ▪ Search ▪ Testing ▪ Change Management▪ Management platforms
▪ Design Focus
17
The Open API Initiative
18
The Open API Initiative - MissionProvide 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
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
OAI Governance Structure
21
BusinessGovernance
Board(BGB)
Budget,marketing,community,etc…
TechnicalDeveloperCommunity
(TDC)
ManagestheOpenAPI
Specification
TechnicalOversightBoard(TOB)
ResolvesconflictinTDC
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
Focus of OpenAPI Spec 3.0
Aiming for 2016 summer release ~mid July23
Documentation
Structure
ProtocolsandPayloads
JSONSchema&JSON
References
URISupportError
Handling/Documentation
Security RequestParameters
24
OAS Usage Examples
25
Code First with Swagger Annotations
26
Swagger UI
Builddocsbyprocessing
JSON/YAMLAPISpec
TheAPISpeccanbereturned fromstaticsourceorfromthe
running API
27
API First with Swagger Editor
WrappedSwaggerEditor
Lifecycle Tooling
ManageAPIMetadata
Governance&Review
DynamicMockResponses
And Finally…
28
Get Involved!Website: https://openapis.org/
Spec: https://github.com/oai
Follow: @OpenApiSpec
29
Additional Information
30
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
OpenAPI Spec’s X-Extensions
paths:/demo/bankthings:
get:summary: Returns a list of Bank ThingsoperationId: getBankThingsx-c1-proxy: auditparameters:
- $ref: '#/parameters/ApiKey'
33
From Legacy Java Framework to Polyglot Microservices using OpenAPI
@Annotations & Servlet Filters ➔ X-Extensions