The document introduces Swagger as a solution for the inconsistent integration with REST APIs, addressing challenges like varying client libraries and documentation. It explains how Swagger provides a structured method for API self-declaration, enabling client library generation, sandbox testing, and consistent error responses. The document encourages developers to utilize Swagger for better API development and offers resources for further exploration.

1. Introduction to SwaggerTony Tam@fehguy

2. Why Swagger?Integration with REST APIs is troublesome and inconsistentDifferent vendors have different REST semanticsClient libraries vary wildly by vendor, languageDocumentation for developers is an afterthoughtInput parameters, allowable values, models, responses are found via trial & errorInternally a PITAYOUR API is too hard to develop against!

3. How Does it Work?Your server produces a Resource ListAll available APIshttp://petstore.swagger.wordnik.com/api/resources.json“It’s like a sitemap for your API!”

4. How Does it Work?Each API declares itselfAvailable operationsParametersType (path, query, body)Allowable values/data typesInput/output modelsError responses with descriptions

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

6. API ResponseKnowing 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 GenerationCode generation based on Resource SpecTemplate-based FrameworkConsume REST Methods, Models, ParametersProduce client libraries“Know before you go HTTP”Required values, fields are known by the clientOnly expose what’s allowed!Swagger filtering removes methods/models you don’t have access to

9. Client Library GenerationSuper user accessOrdinary dev access

10. Test FrameworkJSON-driven tests for your Client + APIExpected dataTest Suites

11. Test Framework

12. Easy to addFor Java/Scala via JAX-RS…Add swagger-core.jarAnnotate your models per your @ProviderclassAnnotate your resources

13. Easy to addFor node.js via expressRequire swagger.jsDeclare your swagger specs, modelsCould use AST/DSL to do automaticallyAdd your operations, configure and start

14. Easy DIYThe Swagger spec is Language Agnostic!ANY swagger-compliant server can…Use the Swagger client lib generatorUse the test frameworkUse the sandbox UIMore server support from WordnikPlay, Rails.net, others community developed

15. Where to go NextTry Swaggerswagger.wordnik.comSee it in actiondeveloper.wordnik.com/docsDownload the source/samplesswagger.wordnik.com/downloadsDiscuss itgroups.google.com/group/wordnik-api#swagger_doc on freenode

16. Questions?