Swagger is a specification and complete framework implementation for describing, producing, consuming, and visualizing RESTful web services.

1. Introduction to Swagger Tony Tam @fehguy

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

5. API Response http://petstore.swagger.wordnik.com/api/pet.json

6. API Response Knowing input/output models is helpful! Based on JSON Schema (Draft) http://tools.ietf.org/html/draft-zyp-json-schema-03

7. But what’s the benefit? A Sandbox!

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

9. Client Library Generation Super user access Ordinary dev access

10. Test Framework JSON-driven tests for your Client + API Expected data Test Suites

11. Test Framework

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

16. Questions?