Introduction to Swagger

Tony Tam@fehguy

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!

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!”

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

API Response

http://petstore.swagger.wordnik.com/api/pet.json

API Response

•Knowing input/output models is helpful!

Based on JSON

Schema (Draft)

http://tools.ietf.org/html/draft-zyp-json-schema-03

But what’s the benefit?

•A Sandbox!

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

Client Library GenerationOrdinary dev access

Super user

access

Test Framework

•JSON-driven tests for your Client + API

Expected dataTest Suites

Test Framework

Easy to add

•For Java/Scala via JAX-RS…

• Add swagger-core.jar

• Annotate your models per your @Provider class

• Annotate your resources

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

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

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

Questions?