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

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