Swagger APIs for Humans and Robots (Gluecon)
•
9 likes•7,858 views
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
More Related Content
What's hot
What's hot (20)
Viewers also liked
Viewers also liked (10)
Similar to Swagger APIs for Humans and Robots (Gluecon)
Similar to Swagger APIs for Humans and Robots (Gluecon) (20)
More from Tony Tam
More from Tony Tam (16)
Recently uploaded
Recently uploaded (20)
Swagger APIs for Humans and Robots (Gluecon)
- 1. Swagger APIs for Humans (and Robots) @fehguy
- 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
- 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!
- 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
Editor's Notes
- Services, internal or external, are the new unit of software
- How modules are documented varies wildly by language, technology