Presentation to Gluecon 2014 about Swagger for API development and adoption of services. Reverb also announced the Swagger 2.0 Working Group, with Apigee as a founding member

1. Swagger APIs for Humans
(and Robots)
@fehguy

2. Swagger Philosophy

3. Swagger Philosophy
Service documentation sucks
typically

4. 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

5. Swagger Philosophy
• Solved by machine-readable, discoverable
API contract
• Should speed up, not slow down
development process
• External services/proxies not required

6. 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

7. 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

8. 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

9. Swagger UI

10. Client SDKs
• Your consumers want to use your service
– How they want
– Not write your software

11. 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!

12. Client Generation
https://github.com/wordnik/swagger-codegen
• Templates can be generated your way
• Typed and untyped languages
Groovy Java Android
async-scala C# Flash
Objective C PHP Python
Python 3 Ruby Scala

13. 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

14. Client Generation
• Configuration Script
– Packages
– Imports
– Type Mapping
– Packaging info
• Group ID, Artifact ID, version
• Templates
– Boilerplate code

15. Client Generation
• Codegen for client generation

16. Static Doc Generation
• Codegen !== client generation
• Templates are generic

17. Static Doc Generation

18. Server Generation
• Specs can generate servers

19. How do you write Software?
• Code first?
• Design first?
• Hybrid?
One size does NOT fit all

20. Top Down vs. Bottom-up
• Design-first is not this (anymore)

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

22. Top Down?
XML: 453 Lines JSON: 512 Lines YAML: 400 Lines
It’s not
about the
line count!

23. Introducing Swagger Editor!

24. 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

26. 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

27. 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

28. Swagger is FOSS
• Apache 2 License
https://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

29. Where to go for help
Google Groups
• https://groups.google.com/forum/#!forum/s
wagger-swaggersocket
IRC
• irc.freenode.net
Email
• apiteam@wordnik.com