The Swagger Format becomes the Open API Specification: Standardizing descriptions of Web APIs for interoperability

Steven WillmottCEO, 3scale Inc.

steve@3scale.net : @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

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)

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

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

Community

10 December 2014DRAFT - Open API Initiative 10

Broad Industry Adoption

11

Why adopt the OpenAPI Specification?

12

Commitment to Remain

OpenPortable

Vendor Neutral

Strong Independent Sponsorship

CommunitySimple & Pragmatic

Superior Tooling Best Industry Support

The Importance of API Interface Definitions

13

14

What about Rest Interfaces?

2010s

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

In your organization: inter-team dependencies

Across the public Internet: cross-organization discovery & 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

Business Governance

Board (BGB)

Budget, marketing, community, etc…

Technical Developer

Community(TDC)

Manages the OpenAPI

Specification

Technical Oversight

Board(TOB)

Resolves conflict in TDC

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

DocumentationStructure

Protocols and Payloads

JSON Schema & JSON

References

URI SupportError

Handling/Documentation

Security Request Parameters

24

OAS Usage Examples

25

Code First with Swagger Annotations

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

API First with Swagger Editor

Wrapped Swagger Editor

Lifecycle Tooling

Manage API Metadata

Governance & Review

Dynamic Mock Responses

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 Things operationId: getBankThings x-c1-proxy: audit parameters: - $ref: '#/parameters/ApiKey'

33

From Legacy Java Framework to Polyglot Microservices using OpenAPI

@Annotations & Servlet Filters ➔ X-Extensions