The document outlines the philosophy and functionality of Swagger, which provides a machine-readable, discoverable API contract to enhance communication between services and developers. It discusses the ease of API definition using JSON, supporting tools for client and server generation, and highlights the community involvement in its development. Additionally, it emphasizes the movement towards a design-first approach and includes resources for further engagement and support.

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