Swagger APIs for Humans and Robots (Gluecon)
Download as PPTX, PDF9 likes7,899 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
Ad
More Related Content
What's hot (20)
Viewers also liked (10)
Ad
Similar to Swagger APIs for Humans and Robots (Gluecon) (20)
Ad
More from Tony Tam (16)
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 โข [email protected]