swagger - make your api accessible
DESCRIPTION
Presented at http://devcon-oct13.events.co.il/TRANSCRIPT
![Page 2: Swagger - make your API accessible](https://reader036.vdocuments.net/reader036/viewer/2022081504/554f73ceb4c9052a518b45d6/html5/thumbnails/2.jpg)
Personal
My name is Victor
Almost 15 years of software development
Chief Architect @
![Page 3: Swagger - make your API accessible](https://reader036.vdocuments.net/reader036/viewer/2022081504/554f73ceb4c9052a518b45d6/html5/thumbnails/3.jpg)
Architecture
SOA
APIs
https://twitter.com/dcorpa
![Page 4: Swagger - make your API accessible](https://reader036.vdocuments.net/reader036/viewer/2022081504/554f73ceb4c9052a518b45d6/html5/thumbnails/4.jpg)
Architecture
APIs are for humans
Documentation
http://www.infoq.com/resource/presentations/API-Humans/en/slides/sl23.jpg
![Page 5: Swagger - make your API accessible](https://reader036.vdocuments.net/reader036/viewer/2022081504/554f73ceb4c9052a518b45d6/html5/thumbnails/5.jpg)
Documentation
![Page 6: Swagger - make your API accessible](https://reader036.vdocuments.net/reader036/viewer/2022081504/554f73ceb4c9052a518b45d6/html5/thumbnails/6.jpg)
Documentation
• No standard• Ad-hoc attributes• Managed manually• Not up to date• …..
http://www.imagineyourreality.com/business-coaching/documentation.html
![Page 7: Swagger - make your API accessible](https://reader036.vdocuments.net/reader036/viewer/2022081504/554f73ceb4c9052a518b45d6/html5/thumbnails/7.jpg)
API Listing
![Page 8: Swagger - make your API accessible](https://reader036.vdocuments.net/reader036/viewer/2022081504/554f73ceb4c9052a518b45d6/html5/thumbnails/8.jpg)
API Operations
![Page 9: Swagger - make your API accessible](https://reader036.vdocuments.net/reader036/viewer/2022081504/554f73ceb4c9052a518b45d6/html5/thumbnails/9.jpg)
API parameters and return types
![Page 10: Swagger - make your API accessible](https://reader036.vdocuments.net/reader036/viewer/2022081504/554f73ceb4c9052a518b45d6/html5/thumbnails/10.jpg)
Swagger is…
• producing• consuming• visualizing
RESTful APIs
A frameworkfor
• describing• documenting
RESTful APIs
A specificationfor
Technology Methodology
![Page 11: Swagger - make your API accessible](https://reader036.vdocuments.net/reader036/viewer/2022081504/554f73ceb4c9052a518b45d6/html5/thumbnails/11.jpg)
The Swagger Specification
It’s a spec!• JSON to specify metadata• JSON to specify API structure• JSON schema for the model
specification• Machine readable• Language agnostic
![Page 12: Swagger - make your API accessible](https://reader036.vdocuments.net/reader036/viewer/2022081504/554f73ceb4c9052a518b45d6/html5/thumbnails/12.jpg)
Agenda• Introduction• Deep Dive• The technology• Swagger is not• Alternatives• Dev process• Deployment process• References
![Page 13: Swagger - make your API accessible](https://reader036.vdocuments.net/reader036/viewer/2022081504/554f73ceb4c9052a518b45d6/html5/thumbnails/13.jpg)
Deep Dive
![Page 14: Swagger - make your API accessible](https://reader036.vdocuments.net/reader036/viewer/2022081504/554f73ceb4c9052a518b45d6/html5/thumbnails/14.jpg)
Swagger - API Listing
![Page 15: Swagger - make your API accessible](https://reader036.vdocuments.net/reader036/viewer/2022081504/554f73ceb4c9052a518b45d6/html5/thumbnails/15.jpg)
Swagger - API Listing - JSON
![Page 16: Swagger - make your API accessible](https://reader036.vdocuments.net/reader036/viewer/2022081504/554f73ceb4c9052a518b45d6/html5/thumbnails/16.jpg)
Swagger – API Listing - Annotations
![Page 17: Swagger - make your API accessible](https://reader036.vdocuments.net/reader036/viewer/2022081504/554f73ceb4c9052a518b45d6/html5/thumbnails/17.jpg)
Swagger - API Details
![Page 18: Swagger - make your API accessible](https://reader036.vdocuments.net/reader036/viewer/2022081504/554f73ceb4c9052a518b45d6/html5/thumbnails/18.jpg)
Swagger – Test the API
![Page 19: Swagger - make your API accessible](https://reader036.vdocuments.net/reader036/viewer/2022081504/554f73ceb4c9052a518b45d6/html5/thumbnails/19.jpg)
Swagger - API Details - JSON
![Page 20: Swagger - make your API accessible](https://reader036.vdocuments.net/reader036/viewer/2022081504/554f73ceb4c9052a518b45d6/html5/thumbnails/20.jpg)
Swagger – API Details - Annotations
![Page 21: Swagger - make your API accessible](https://reader036.vdocuments.net/reader036/viewer/2022081504/554f73ceb4c9052a518b45d6/html5/thumbnails/21.jpg)
The Technology
![Page 22: Swagger - make your API accessible](https://reader036.vdocuments.net/reader036/viewer/2022081504/554f73ceb4c9052a518b45d6/html5/thumbnails/22.jpg)
Reverb - Wordnik
Atmosphere – Scalatra – JSON4S
![Page 23: Swagger - make your API accessible](https://reader036.vdocuments.net/reader036/viewer/2022081504/554f73ceb4c9052a518b45d6/html5/thumbnails/23.jpg)
The Technology – Scala based
• swagger-core• swagger-codegen• swagger-ui
![Page 24: Swagger - make your API accessible](https://reader036.vdocuments.net/reader036/viewer/2022081504/554f73ceb4c9052a518b45d6/html5/thumbnails/24.jpg)
Server side integrations
• Django• Node.js• JAX-RS• RESTEasy• Grails• Play 2• Scalatra• go-restful
• SpringMVC• ServiceStack .net/MONO• Swagger-PHP• Symphony 2• Grape-swagger for Ruby• Octohipster for Clojure• More…
![Page 25: Swagger - make your API accessible](https://reader036.vdocuments.net/reader036/viewer/2022081504/554f73ceb4c9052a518b45d6/html5/thumbnails/25.jpg)
Client code generation
• Java• Scala• Groovy• Clojure• Python• Ruby
• ObjectiveC• C#• PHP• Javascript• Custom
• Uses {{mustache}} templates
![Page 26: Swagger - make your API accessible](https://reader036.vdocuments.net/reader036/viewer/2022081504/554f73ceb4c9052a518b45d6/html5/thumbnails/26.jpg)
Swagger is not
![Page 27: Swagger - make your API accessible](https://reader036.vdocuments.net/reader036/viewer/2022081504/554f73ceb4c9052a518b45d6/html5/thumbnails/27.jpg)
• Does not support multiple 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
![Page 28: Swagger - make your API accessible](https://reader036.vdocuments.net/reader036/viewer/2022081504/554f73ceb4c9052a518b45d6/html5/thumbnails/28.jpg)
Alternatives
![Page 29: Swagger - make your API accessible](https://reader036.vdocuments.net/reader036/viewer/2022081504/554f73ceb4c9052a518b45d6/html5/thumbnails/29.jpg)
• SOAP/WSDL– http://www.w3.org/TR/wsdl
• WADL– http://en.wikipedia.org/wiki/
Web_Application_Description_Language
• Mashery IO-Docs – http://www.mashery.com/product/io-docs– https://github.com/mashery/iodocs
• http://apiary.io/• Homegrown
![Page 30: Swagger - make your API accessible](https://reader036.vdocuments.net/reader036/viewer/2022081504/554f73ceb4c9052a518b45d6/html5/thumbnails/30.jpg)
Dev Process
![Page 31: Swagger - make your API accessible](https://reader036.vdocuments.net/reader036/viewer/2022081504/554f73ceb4c9052a518b45d6/html5/thumbnails/31.jpg)
API development approaches
API specification first
–Write the JSON spec–Generate the API stubs–Implement the APIs
–Publish
![Page 32: Swagger - make your API accessible](https://reader036.vdocuments.net/reader036/viewer/2022081504/554f73ceb4c9052a518b45d6/html5/thumbnails/32.jpg)
API development approaches
API implementation first
–Implement the API–Put the annotations in place
![Page 33: Swagger - make your API accessible](https://reader036.vdocuments.net/reader036/viewer/2022081504/554f73ceb4c9052a518b45d6/html5/thumbnails/33.jpg)
Deployment Process
![Page 34: Swagger - make your API accessible](https://reader036.vdocuments.net/reader036/viewer/2022081504/554f73ceb4c9052a518b45d6/html5/thumbnails/34.jpg)
Dev/Test environment
Annotate the APIs
Make swagger UI accessible from the application itself
![Page 35: Swagger - make your API accessible](https://reader036.vdocuments.net/reader036/viewer/2022081504/554f73ceb4c9052a518b45d6/html5/thumbnails/35.jpg)
Dev/Test environment
View the documentation locally
Test the APIs using swagger UI
![Page 36: Swagger - make your API accessible](https://reader036.vdocuments.net/reader036/viewer/2022081504/554f73ceb4c9052a518b45d6/html5/thumbnails/36.jpg)
Dev/Test environment
Generate internal clients based on swagger specification
![Page 37: Swagger - make your API accessible](https://reader036.vdocuments.net/reader036/viewer/2022081504/554f73ceb4c9052a518b45d6/html5/thumbnails/37.jpg)
Production environment
Make swagger UI NOT accessible from the application
itself
![Page 38: Swagger - make your API accessible](https://reader036.vdocuments.net/reader036/viewer/2022081504/554f73ceb4c9052a518b45d6/html5/thumbnails/38.jpg)
Production environment
Automatically generate external swagger static resources
![Page 39: Swagger - make your API accessible](https://reader036.vdocuments.net/reader036/viewer/2022081504/554f73ceb4c9052a518b45d6/html5/thumbnails/39.jpg)
Production environment
Deploy on dedicated web server
Synchronize the documentation
![Page 40: Swagger - make your API accessible](https://reader036.vdocuments.net/reader036/viewer/2022081504/554f73ceb4c9052a518b45d6/html5/thumbnails/40.jpg)
Production environment
Generate external clients based on swagger specification
![Page 41: Swagger - make your API accessible](https://reader036.vdocuments.net/reader036/viewer/2022081504/554f73ceb4c9052a518b45d6/html5/thumbnails/41.jpg)
References
• Swagger home: – https://developers.helloreverb.com/swagger/
• Swagger specification– https://github.com/wordnik/swagger-core/wiki
• Swagger Demo– http://petstore.swagger.wordnik.com/
• Wordnik APIs– http://developer.wordnik.com/docs.html#!/account
![Page 42: Swagger - make your API accessible](https://reader036.vdocuments.net/reader036/viewer/2022081504/554f73ceb4c9052a518b45d6/html5/thumbnails/42.jpg)
Make your API accessible
Use Swagger!