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
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
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
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
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
Notes de l'éditeur
Services, internal or external, are the new unit of software
How modules are documented varies wildly by language, technology