the swagger format becomes the open api specification: standardizing descriptions of web apis for...
TRANSCRIPT
![Page 1: The Swagger Format becomes the Open API Specification: Standardizing descriptions of Web APIs for interoperability](https://reader035.vdocuments.site/reader035/viewer/2022081517/587132be1a28abf0568b4d93/html5/thumbnails/1.jpg)
The Swagger Format becomes the Open API Specification: Standardizing descriptions of Web APIs for interoperability
Steven WillmottCEO, 3scale Inc.
[email protected] : @njyx
![Page 2: The Swagger Format becomes the Open API Specification: Standardizing descriptions of Web APIs for interoperability](https://reader035.vdocuments.site/reader035/viewer/2022081517/587132be1a28abf0568b4d93/html5/thumbnails/2.jpg)
Credits
2
▪ Slides from Marsh Gardiner (Apigee), Dennis Brenan (Capital One), Tony Tam (Smartbear), Ole Lensmar (Smartbear) and myself
▪ http://openapis.org/
![Page 3: The Swagger Format becomes the Open API Specification: Standardizing descriptions of Web APIs for interoperability](https://reader035.vdocuments.site/reader035/viewer/2022081517/587132be1a28abf0568b4d93/html5/thumbnails/3.jpg)
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
![Page 4: The Swagger Format becomes the Open API Specification: Standardizing descriptions of Web APIs for interoperability](https://reader035.vdocuments.site/reader035/viewer/2022081517/587132be1a28abf0568b4d93/html5/thumbnails/4.jpg)
Introduction & Agenda
4
▪OpenAPI Specification (OAS)▪Open API Initiative (OAI)▪Usage and Tooling Examples
![Page 5: The Swagger Format becomes the Open API Specification: Standardizing descriptions of Web APIs for interoperability](https://reader035.vdocuments.site/reader035/viewer/2022081517/587132be1a28abf0568b4d93/html5/thumbnails/5.jpg)
The OpenAPI Specificationfka “the Swagger specification”
DRAFT - Open API Initiative (OAI) 5
![Page 6: The Swagger Format becomes the Open API Specification: Standardizing descriptions of Web APIs for interoperability](https://reader035.vdocuments.site/reader035/viewer/2022081517/587132be1a28abf0568b4d93/html5/thumbnails/6.jpg)
What is the OpenAPI Specification?
6
Generally CategorizedREST API Description Language
More GenerallyIDL for REST APIs
![Page 7: The Swagger Format becomes the Open API Specification: Standardizing descriptions of Web APIs for interoperability](https://reader035.vdocuments.site/reader035/viewer/2022081517/587132be1a28abf0568b4d93/html5/thumbnails/7.jpg)
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)
![Page 8: The Swagger Format becomes the Open API Specification: Standardizing descriptions of Web APIs for interoperability](https://reader035.vdocuments.site/reader035/viewer/2022081517/587132be1a28abf0568b4d93/html5/thumbnails/8.jpg)
Road to the OAS
8
2010 Tony 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
![Page 9: The Swagger Format becomes the Open API Specification: Standardizing descriptions of Web APIs for interoperability](https://reader035.vdocuments.site/reader035/viewer/2022081517/587132be1a28abf0568b4d93/html5/thumbnails/9.jpg)
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
![Page 10: The Swagger Format becomes the Open API Specification: Standardizing descriptions of Web APIs for interoperability](https://reader035.vdocuments.site/reader035/viewer/2022081517/587132be1a28abf0568b4d93/html5/thumbnails/10.jpg)
Community
10 December 2014DRAFT - Open API Initiative 10
![Page 11: The Swagger Format becomes the Open API Specification: Standardizing descriptions of Web APIs for interoperability](https://reader035.vdocuments.site/reader035/viewer/2022081517/587132be1a28abf0568b4d93/html5/thumbnails/11.jpg)
Broad Industry Adoption
11
![Page 12: The Swagger Format becomes the Open API Specification: Standardizing descriptions of Web APIs for interoperability](https://reader035.vdocuments.site/reader035/viewer/2022081517/587132be1a28abf0568b4d93/html5/thumbnails/12.jpg)
Why adopt the OpenAPI Specification?
12
Commitment to Remain
OpenPortable
Vendor Neutral
Strong Independent Sponsorship
CommunitySimple & Pragmatic
Superior Tooling Best Industry Support
![Page 13: The Swagger Format becomes the Open API Specification: Standardizing descriptions of Web APIs for interoperability](https://reader035.vdocuments.site/reader035/viewer/2022081517/587132be1a28abf0568b4d93/html5/thumbnails/13.jpg)
The Importance of API Interface Definitions
13
![Page 14: The Swagger Format becomes the Open API Specification: Standardizing descriptions of Web APIs for interoperability](https://reader035.vdocuments.site/reader035/viewer/2022081517/587132be1a28abf0568b4d93/html5/thumbnails/14.jpg)
14
What about Rest Interfaces?
2010s
![Page 15: The Swagger Format becomes the Open API Specification: Standardizing descriptions of Web APIs for interoperability](https://reader035.vdocuments.site/reader035/viewer/2022081517/587132be1a28abf0568b4d93/html5/thumbnails/15.jpg)
15
What Spec? Spec Generates Code
Spec as Code
Code is Spec
REST API Development Evolution
![Page 16: The Swagger Format becomes the Open API Specification: Standardizing descriptions of Web APIs for interoperability](https://reader035.vdocuments.site/reader035/viewer/2022081517/587132be1a28abf0568b4d93/html5/thumbnails/16.jpg)
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
![Page 17: The Swagger Format becomes the Open API Specification: Standardizing descriptions of Web APIs for interoperability](https://reader035.vdocuments.site/reader035/viewer/2022081517/587132be1a28abf0568b4d93/html5/thumbnails/17.jpg)
Shared Definitions are Crucial
▪Fixed point of Reference▪Automation:▪Explorers / Docs▪Code Gen ▪Editors ▪Search ▪Testing ▪Change Management▪Management platforms
▪Design Focus
17
![Page 18: The Swagger Format becomes the Open API Specification: Standardizing descriptions of Web APIs for interoperability](https://reader035.vdocuments.site/reader035/viewer/2022081517/587132be1a28abf0568b4d93/html5/thumbnails/18.jpg)
The Open API Initiative
18
![Page 19: The Swagger Format becomes the Open API Specification: Standardizing descriptions of Web APIs for interoperability](https://reader035.vdocuments.site/reader035/viewer/2022081517/587132be1a28abf0568b4d93/html5/thumbnails/19.jpg)
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
![Page 20: The Swagger Format becomes the Open API Specification: Standardizing descriptions of Web APIs for interoperability](https://reader035.vdocuments.site/reader035/viewer/2022081517/587132be1a28abf0568b4d93/html5/thumbnails/20.jpg)
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
![Page 21: The Swagger Format becomes the Open API Specification: Standardizing descriptions of Web APIs for interoperability](https://reader035.vdocuments.site/reader035/viewer/2022081517/587132be1a28abf0568b4d93/html5/thumbnails/21.jpg)
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
![Page 22: The Swagger Format becomes the Open API Specification: Standardizing descriptions of Web APIs for interoperability](https://reader035.vdocuments.site/reader035/viewer/2022081517/587132be1a28abf0568b4d93/html5/thumbnails/22.jpg)
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
![Page 23: The Swagger Format becomes the Open API Specification: Standardizing descriptions of Web APIs for interoperability](https://reader035.vdocuments.site/reader035/viewer/2022081517/587132be1a28abf0568b4d93/html5/thumbnails/23.jpg)
Focus of OpenAPI Spec 3.0
Aiming for 2016 summer release ~mid July23
DocumentationStructure
Protocols and Payloads
JSON Schema & JSON
References
URI SupportError
Handling/Documentation
Security Request Parameters
![Page 24: The Swagger Format becomes the Open API Specification: Standardizing descriptions of Web APIs for interoperability](https://reader035.vdocuments.site/reader035/viewer/2022081517/587132be1a28abf0568b4d93/html5/thumbnails/24.jpg)
24
OAS Usage Examples
![Page 25: The Swagger Format becomes the Open API Specification: Standardizing descriptions of Web APIs for interoperability](https://reader035.vdocuments.site/reader035/viewer/2022081517/587132be1a28abf0568b4d93/html5/thumbnails/25.jpg)
25
Code First with Swagger Annotations
![Page 26: The Swagger Format becomes the Open API Specification: Standardizing descriptions of Web APIs for interoperability](https://reader035.vdocuments.site/reader035/viewer/2022081517/587132be1a28abf0568b4d93/html5/thumbnails/26.jpg)
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
![Page 27: The Swagger Format becomes the Open API Specification: Standardizing descriptions of Web APIs for interoperability](https://reader035.vdocuments.site/reader035/viewer/2022081517/587132be1a28abf0568b4d93/html5/thumbnails/27.jpg)
27
API First with Swagger Editor
Wrapped Swagger Editor
Lifecycle Tooling
Manage API Metadata
Governance & Review
Dynamic Mock Responses
![Page 28: The Swagger Format becomes the Open API Specification: Standardizing descriptions of Web APIs for interoperability](https://reader035.vdocuments.site/reader035/viewer/2022081517/587132be1a28abf0568b4d93/html5/thumbnails/28.jpg)
And Finally…
28
![Page 29: The Swagger Format becomes the Open API Specification: Standardizing descriptions of Web APIs for interoperability](https://reader035.vdocuments.site/reader035/viewer/2022081517/587132be1a28abf0568b4d93/html5/thumbnails/29.jpg)
Get Involved!Website: https://openapis.org/
Spec: https://github.com/oai
Follow: @OpenApiSpec
29
![Page 30: The Swagger Format becomes the Open API Specification: Standardizing descriptions of Web APIs for interoperability](https://reader035.vdocuments.site/reader035/viewer/2022081517/587132be1a28abf0568b4d93/html5/thumbnails/30.jpg)
Additional Information
30
![Page 31: The Swagger Format becomes the Open API Specification: Standardizing descriptions of Web APIs for interoperability](https://reader035.vdocuments.site/reader035/viewer/2022081517/587132be1a28abf0568b4d93/html5/thumbnails/31.jpg)
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
![Page 32: The Swagger Format becomes the Open API Specification: Standardizing descriptions of Web APIs for interoperability](https://reader035.vdocuments.site/reader035/viewer/2022081517/587132be1a28abf0568b4d93/html5/thumbnails/32.jpg)
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'
![Page 33: The Swagger Format becomes the Open API Specification: Standardizing descriptions of Web APIs for interoperability](https://reader035.vdocuments.site/reader035/viewer/2022081517/587132be1a28abf0568b4d93/html5/thumbnails/33.jpg)
33
From Legacy Java Framework to Polyglot Microservices using OpenAPI
@Annotations & Servlet Filters ➔ X-Extensions