Swagger - Make your REST APIs accessible - Victor Trakhtenberg
47
-
Upload
codemotion-tel-aviv -
Category
Technology
-
view
197 -
download
3
Transcript of Swagger - Make your REST APIs accessible - Victor Trakhtenberg
Personal
My name is Victor
Personal
Java.IL community co-‐founder
http://www.meetup.com/JavaIL/
Personal
Full Stack Engineer @
http://vatuma.com/demo/wp-content/uploads/2009/11/sun.jpg
http://toonclips.com/design/828
hFp://www.appdynamics.com/blog/wp-‐content/uploads/2012/11/producMonCraziness2.png
http://thehandcraPedstory.com/wp-content/uploads/2014/08/we-all-have-a-story-to-tell.jpg
Architecture Monolith
to Micro Services
APIs
hFps://twiFer.com/dcorpa
Architecture
APIs are for humans
DocumentaMon
hFp://www.infoq.com/resource/presentaMons/API-‐Humans/en/slides/sl23.jpg
DocumentaMon
DocumentaMon
• No standard • Ad-‐hoc aFributes • Managed manually • Not up to date • …..
hFp://www.imagineyourreality.com/business-‐coaching/documentaMon.html
API LisMng
API OperaMons
API parameters and return types
Swagger is…
• producing • consuming • visualizing
RESTful APIs
A framework for
• describing • documenMng
RESTful APIs
A specificaMon for
Technology
Methodology
The Swagger SpecificaMon
It’s a spec! • JSON to specify metadata • JSON to specify API structure • JSON schema for the model specificaMon
• Machine readable • Language agnosMc
Agenda • IntroducMon • Deep Dive • The technology • Swagger is not • Swagger 2.0 • AlternaMves • References
Deep Dive
Swagger -‐ API LisMng
Swagger -‐ API LisMng -‐ JSON
Swagger – API LisMng -‐ AnnotaMons
Swagger -‐ API Details
Swagger – Test the API
Swagger -‐ API Details -‐ JSON
Swagger – API Details -‐ AnnotaMons
The Technology
Reverb -‐ Wordnik
Atmosphere – Scalatra – JSON4S
The Technology – Scala based
• swagger-‐core • swagger-‐codegen • swagger-‐ui
• swagger-‐js • swagger-‐socket
Server side integraMons
• Django • Node.js • JAX-‐RS • RESTEasy • Grails • Play 2 • Scalatra • go-‐rescul
• SpringMVC • ServiceStack .net/MONO • Swagger-‐PHP • Symphony 2 • Grape-‐swagger for Ruby • Octohipster for Clojure • More…
Client code generaMon
• Java • Scala • Groovy • Clojure • Python • Ruby
• ObjecMveC • C# • PHP • Javascript • Custom
• Uses {{mustache}} templates
Swagger is not
• Does not support mulMple API versions • Does not tell how to write the API
– Delete an object by HTTP DELETE or via HTTP GET with query param
• Is not trying to solve all problems for all APIs
Swagger 2.0
Emerging Standard
• Thousands of developers contributed to the ecosystem
• Tens of thousands of producMon deployments
• From startups to US Government
http://www.marketwatch.com/story/reverb-announces-swagger-20-a-next-generation-interface-to-connect-apis-and-cloud-services-2014-09-08?mod=mw_share_twitter
Swagger 2.0
• YAML support (along with JSON) • OAuth 2.0 enabled • Migrated to Java • Won’t be compaMble with 1.x
Swagger.io
Swagger Tools
Swagger UI
Swagger Tools
Swagger Tools
AlternaMves
• SOAP/WSDL – h?p://www.w3.org/TR/wsdl
• WADL – h?p://en.wikipedia.org/wiki/Web_ApplicaJon_DescripJon_Language
• Mashery IO-‐Docs – h?p://www.mashery.com/product/io-‐docs – h?ps://github.com/mashery/iodocs
• hFp://apiary.io/ • MuleSoP (RAML)
– h?p://api-‐portal.anypoint.mulesoL.com/raml-‐tools?ref=apihub
• Homegrown
References • Swagger home:
– h?ps://developers.helloreverb.com/swagger/
• Swagger specificaMon – h?ps://github.com/wordnik/swagger-‐core/wiki
• Swagger Demo – h?p://petstore.swagger.wordnik.com/
• Swagger.io • Swagger editor
– h?p://editor.swagger.io/
• Wordnik APIs – h?p://developer.wordnik.com/docs.html#!/account
Make your API accessible
Use Swagger!
