Swagger APIs for Humans (and Robots) @fehguy
May 11, 2015
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• [email protected]