Swagger for your REST API Tony Tam

REST as the “new” API

Revisiting the JAR

•  Expose & share low-level functionality

•  Reduced plumbing, focus on business logic

•  Helped us build big, monolithic apps

•  Dependency hell

REST as the “new” API

•  Complex building blocks for your application •  Authentication •  Photo storage •  Analytics

•  Language & deployment independent

•  Vertical scaling addressed by smaller, decoupled services

Integrating 3rd Party APIs

How about Documentation?"

Integrating 3rd Party APIs

How about Documentation?"

Javadocs?"

Stack Overflow?"

IDE support?"

JSDoc?"

Integrating 3rd Party APIs

Integrating 3rd Party APIs

Integrating 3rd Party APIs

Integrating 3rd Party APIs

So… How do we describe APIs?

Developer Docs?"

WADL"WADL2?"

WSDL?"

Javadocs?"

The Swagger Specification

It’s a spec! •  JSON •  Coupled of decoupled •  Machine-readable •  Language agnostic •  Distributed by Design

An Interface for your API

Benefits of an Interface

It’s done in JSON •  Generate manually

•  Deploy statically •  Generate automatically by server integration

•  9 languages, 16+ frameworks

Existing API?

Benefits of an Interface

Machine-readable Your boss can try your

API

Swagger Spec Server"

Benefits of an Interface

Distributed design

/pet"

/store"

/user"

Server 1"

Server 2"

Server 3"

Resource"Listing"

API Declaration"

How does this help you?

Client-Side Developer"

Server"Developer"

How does this help you?

Client-Side Developer"

OMG I can code w/o waiting for back end!"

The client developer

isn’t bugging me!"

Server"Developer"

How about your clients?

REST or SDK? •  Please! Strive to

remove your logic from clients

/api/pet.json/1?delete (GET) /api/pet.json/1 (DELETE) /api/pet.json/1 (POST empty)

How about your clients?

REST or SDK? •  Please! Strive to

remove your logic from clients

/api/pet.json/1?delete (GET) /api/pet.json/1 (DELETE) /api/pet.json/1 (POST empty) These all

“work” (This is your job, not your

clients’)

How about your clients?

Swagger can help (if you like) •  Machine-readable => code generator •  Uses non-ghetto {{mustache}} templates •  Make client libraries “your way”

How about your API service?

Swagger can again help (if you like) •  Code-generator, not “client generator” •  Build your server from the interface

Interfaces are nice

•  Developers know what they’re building •  Clients know what they’re getting •  Machines and humans can interpret them •  Teams can develop in parallel

Swagger is FOSS

Where to go next More info + demo http://developers.helloreverb.com/swagger/

Swagger specification https://github.com/wordnik/swagger-core/wiki

JVM server implementation https://github.com/wordnik/swagger-core

Node.js server implementation https://github.com/wordnik/swagger-core

swagger-ui https://github.com/wordnik/swagger-ui

swagger-codegen https://github.com/wordnik/swagger-codegen

@fehguy"