2. 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!
3. How Does it Work? Your server produces a Resource List All available APIs http://petstore.swagger.wordnik.com/api/resources.json “It’s like a sitemap for your API!”
4. 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
8. 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
12. Easy to add For Java/Scala via JAX-RS… Add swagger-core.jar Annotate your models per your @Providerclass Annotate your resources
13. 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
14. 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
15. Where to go Next Try Swagger swagger.wordnik.com See it in action developer.wordnik.com/docs Download the source/samples swagger.wordnik.com/downloads Discuss it groups.google.com/group/wordnik-api #swagger_doc on freenode