Swagger APIs for Humans

(and Robots)

@fehguy

Swagger Philosophy

Swagger Philosophy

Service documentation sucks

typically

Swagger Philosophy

• Communicating is too much work– Users don’t want to write YOUR SDK– If you’re good at Ruby, you suck at GO

• Consumers need a contract– Service logic doesn’t belong in the SDK

• Services are plumbing– We shouldn’t all be plumbers– Business logic is your business

Swagger Philosophy

• Solved by machine-readable, discoverable API contract

• Should speed up, not slow down development process

• External services/proxies not required

What is Swagger?

• An interface to your service– Described in JSON

• It is a contract to your service• Enables “bigotry-free” restful design with

emphasis on getting things done– Many ways to delete a Pet

How does it work?

• Discoverable at runtime, not compile-time• It’s just JSON• No server integration required

– You can describe an API that’s not even yours– Deploy anywhere! Put it on github!– Swagger is JUST a way to describe an API

But Why?

• Machine-readable contract– Description of *everything* the server

can do– Server-controlled documentation– Server/language/platform/deployment

agnostic

• Documentation, code generation, client generation– Like Headers for C, Interfaces for

Java

Swagger UI

Client SDKs

• Your consumers want to use your service– How they want– Not write your software

How do you add Swagger?

• Static Files– Manually crafted JSON

• Heuristics– Traffic inspection

• Code inspection– Code comments, static annotations

• Runtime generation

It’s just JSON!

Client Generation

https://github.com/wordnik/swagger-codegen • Templates can be generated your way• Typed and untyped languages

Groovy Java Androidasync-scala C# FlashObjective C PHP PythonPython 3 Ruby Scala

Client Generation

• Requires a proper API definition• Type info, parameters, input/output models• Protocol, path, authentication• Templates are a starting point

– Clone, configure, put in workflow

Client Generation

• Configuration Script– Packages– Imports– Type Mapping– Packaging info

• Group ID, Artifact ID, version

• Templates– Boilerplate code

Client Generation

• Codegen for client generation

Static Doc Generation

• Codegen !== client generation• Templates are generic

Static Doc Generation

Server Generation

• Specs can generate servers

How do you write Software?

• Code first?• Design first?• Hybrid?

One size does NOT fit all

Top Down vs. Bottom-up

• Design-first is not this (anymore)

Top Down

• GUI vs. XML? The world chose GUI!• GUI vs. JSON?• GUI vs. YAML?

Top Down?

XML: 453 Lines JSON: 512 Lines YAML: 400 Lines

It’s not about the line count!

Introducing Swagger Editor!

Evolution of Swagger

• Swagger Editor– Angular, Ace– OSS, Apache 2.0

• Thank you Community!– 500k downloads of java framework alone– ~10k production deployments– 4k stars, 1600 forks– Big & Small

Swagger 2.0 Working Group

• Give your input on Swagger 2.0 Specification

• Coming this Summer• More info:

– http://swagger.wordnik.com

• Join the evolution– https://github.com/wordnik/swagger-spec

Swagger has a Community

• Server integrations

JAX-RS (java) Scalatra (scala) Spring MVC (java)Spray (scala) Composer (PHP) django (python)Flask (python) Go Maven (JAX-RS)ServiceStack (.net) Doctrine (PHP) Express (JS)Restler (PHP) Hapi (JS) Clojure

Swagger is FOSS

• Apache 2 Licensehttps://github.com/wordnik/swagger-spec

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

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

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

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

https://github.com/wordnik/swagger-node-express

https://github.com/scalatra/scalatra

Where to go for help

Google Groups• https://groups.google.com/forum/#!forum/s

wagger-swaggersocket

IRC• irc.freenode.net

Email• apiteam@wordnik.com