introducing swagger
DESCRIPTION
Swagger is a specification and complete framework implementation for describing, producing, consuming, and visualizing RESTful web services.TRANSCRIPT
![Page 1: Introducing Swagger](https://reader036.vdocuments.site/reader036/viewer/2022081504/554f8f2eb4c9052a518b52ab/html5/thumbnails/1.jpg)
Introduction to Swagger
Tony Tam@fehguy
![Page 2: Introducing Swagger](https://reader036.vdocuments.site/reader036/viewer/2022081504/554f8f2eb4c9052a518b52ab/html5/thumbnails/2.jpg)
Why Swagger?
•Integration with REST APIs is troublesome and inconsistent
• Different vendors have different REST semantics
• Client libraries vary wildly by vendor, language
• Documentation for developers is an afterthought
• Input parameters, allowable values, models, responses are found via trial & error
•Internally a PITA
•YOUR API is too hard to develop against!
![Page 3: Introducing Swagger](https://reader036.vdocuments.site/reader036/viewer/2022081504/554f8f2eb4c9052a518b52ab/html5/thumbnails/3.jpg)
How Does it Work?
•Your server produces a Resource List
• All available APIshttp://petstore.swagger.wordnik.com/api/resources.json
“It’s like a sitemap for your
API!”
![Page 4: Introducing Swagger](https://reader036.vdocuments.site/reader036/viewer/2022081504/554f8f2eb4c9052a518b52ab/html5/thumbnails/4.jpg)
How Does it Work?
•Each API declares itself
• Available operations
• Parameters
• Type (path, query, body)
• Allowable values/data types
• Input/output models
• Error responses with descriptions
![Page 5: Introducing Swagger](https://reader036.vdocuments.site/reader036/viewer/2022081504/554f8f2eb4c9052a518b52ab/html5/thumbnails/5.jpg)
API Response
http://petstore.swagger.wordnik.com/api/pet.json
![Page 6: Introducing Swagger](https://reader036.vdocuments.site/reader036/viewer/2022081504/554f8f2eb4c9052a518b52ab/html5/thumbnails/6.jpg)
API Response
•Knowing input/output models is helpful!
Based on JSON
Schema (Draft)
http://tools.ietf.org/html/draft-zyp-json-schema-03
![Page 7: Introducing Swagger](https://reader036.vdocuments.site/reader036/viewer/2022081504/554f8f2eb4c9052a518b52ab/html5/thumbnails/7.jpg)
But what’s the benefit?
•A Sandbox!
![Page 8: Introducing Swagger](https://reader036.vdocuments.site/reader036/viewer/2022081504/554f8f2eb4c9052a518b52ab/html5/thumbnails/8.jpg)
Client Library Generation
•Code generation based on Resource Spec
• Template-based Framework
• Consume REST Methods, Models, Parameters
• Produce client libraries
•“Know before you go HTTP”
• Required values, fields are known by the client
•Only expose what’s allowed!
• Swagger filtering removes methods/models you don’t have access to
![Page 9: Introducing Swagger](https://reader036.vdocuments.site/reader036/viewer/2022081504/554f8f2eb4c9052a518b52ab/html5/thumbnails/9.jpg)
Client Library GenerationOrdinary dev access
Super user
access
![Page 10: Introducing Swagger](https://reader036.vdocuments.site/reader036/viewer/2022081504/554f8f2eb4c9052a518b52ab/html5/thumbnails/10.jpg)
Test Framework
•JSON-driven tests for your Client + API
Expected dataTest Suites
![Page 11: Introducing Swagger](https://reader036.vdocuments.site/reader036/viewer/2022081504/554f8f2eb4c9052a518b52ab/html5/thumbnails/11.jpg)
Test Framework
![Page 12: Introducing Swagger](https://reader036.vdocuments.site/reader036/viewer/2022081504/554f8f2eb4c9052a518b52ab/html5/thumbnails/12.jpg)
Easy to add
•For Java/Scala via JAX-RS…
• Add swagger-core.jar
• Annotate your models per your @Provider class
• Annotate your resources
![Page 13: Introducing Swagger](https://reader036.vdocuments.site/reader036/viewer/2022081504/554f8f2eb4c9052a518b52ab/html5/thumbnails/13.jpg)
Easy to add
•For node.js via express
• Require swagger.js
• Declare your swagger specs, models
• Could use AST/DSL to do automatically
• Add your operations, configure and start
![Page 14: Introducing Swagger](https://reader036.vdocuments.site/reader036/viewer/2022081504/554f8f2eb4c9052a518b52ab/html5/thumbnails/14.jpg)
Easy DIY
•The Swagger spec is Language Agnostic!
• ANY swagger-compliant server can…
• Use the Swagger client lib generator
• Use the test framework
• Use the sandbox UI
•More server support from Wordnik
• Play, Rails
•.net, others community developed
![Page 15: Introducing Swagger](https://reader036.vdocuments.site/reader036/viewer/2022081504/554f8f2eb4c9052a518b52ab/html5/thumbnails/15.jpg)
Where to go Next
•Try Swaggerswagger.wordnik.com
•See it in actiondeveloper.wordnik.com/docs
•Download the source/samplesswagger.wordnik.com/downloads
•Discuss itgroups.google.com/group/wordnik-api
#swagger_doc on freenode
![Page 16: Introducing Swagger](https://reader036.vdocuments.site/reader036/viewer/2022081504/554f8f2eb4c9052a518b52ab/html5/thumbnails/16.jpg)
Questions?