Service documentation sucks!
• 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!
• Solved by machine-readable, discoverable
• Should speed up, not slow down
• 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!
• Machine-readable contract!
– Description of *everything* the server
– Server-controlled documentation!
• Documentation, code generation,
– Like Headers for C, Interfaces for Java!
How do you add Swagger?!
• Static Files!
– Manually crafted JSON!
– Trafﬁc inspection!
• Code inspection!
– Code comments, static annotations!
• Runtime generation!
It’s just JSON!!
Swagger + Scalatra!
• Scalatra is a Lightweight, High-
performance Micro web framework!
• Extremely clean DSL!
• First-class swagger support!