Swagger

Make your API accessible

Victor Trakhtenberg

victortr75@gmail.com @victortr75

Personal

My name is Victor

Almost 15 years of software development

Chief Architect @

Architecture

SOA

APIs

https://twitter.com/dcorpa

Architecture

APIs are for humans

Documentation

http://www.infoq.com/resource/presentations/API-Humans/en/slides/sl23.jpg

Documentation

Documentation

• No standard• Ad-hoc attributes• Managed manually• Not up to date• …..

http://www.imagineyourreality.com/business-coaching/documentation.html

API Listing

API Operations

API parameters and return types

Swagger is…

• producing• consuming• visualizing

RESTful APIs

A frameworkfor

• describing• documenting

RESTful APIs

A specificationfor

Technology Methodology

The Swagger Specification

It’s a spec!• JSON to specify metadata• JSON to specify API structure• JSON schema for the model

specification• Machine readable• Language agnostic

Agenda• Introduction• Deep Dive• The technology• Swagger is not• Alternatives• Dev process• Deployment process• References

Deep Dive

Swagger - API Listing

Swagger - API Listing - JSON

Swagger – API Listing - Annotations

Swagger - API Details

Swagger – Test the API

Swagger - API Details - JSON

Swagger – API Details - Annotations

The Technology

Reverb - Wordnik

Atmosphere – Scalatra – JSON4S

The Technology – Scala based

• swagger-core• swagger-codegen• swagger-ui

Server side integrations

• Django• Node.js• JAX-RS• RESTEasy• Grails• Play 2• Scalatra• go-restful

• SpringMVC• ServiceStack .net/MONO• Swagger-PHP• Symphony 2• Grape-swagger for Ruby• Octohipster for Clojure• More…

Client code generation

• Java• Scala• Groovy• Clojure• Python• Ruby

• ObjectiveC• C#• PHP• Javascript• Custom

• Uses {{mustache}} templates

Swagger is not

• Does not support multiple API versions• Does not tell how to write the API–Delete an object by HTTP DELETE or via

HTTP GET with query param• Is not trying to solve all problems for all

APIs

Alternatives

• SOAP/WSDL– http://www.w3.org/TR/wsdl

• WADL– http://en.wikipedia.org/wiki/

Web_Application_Description_Language

• Mashery IO-Docs – http://www.mashery.com/product/io-docs– https://github.com/mashery/iodocs

• http://apiary.io/• Homegrown

Dev Process

API development approaches

API specification first

–Write the JSON spec–Generate the API stubs–Implement the APIs

–Publish

API development approaches

API implementation first

–Implement the API–Put the annotations in place

Deployment Process

Dev/Test environment

Annotate the APIs

Make swagger UI accessible from the application itself

Dev/Test environment

View the documentation locally

Test the APIs using swagger UI

Dev/Test environment

Generate internal clients based on swagger specification

Production environment

Make swagger UI NOT accessible from the application

itself

Production environment

Automatically generate external swagger static resources

Production environment

Deploy on dedicated web server

Synchronize the documentation

Production environment

Generate external clients based on swagger specification

References

• Swagger home: – https://developers.helloreverb.com/swagger/

• Swagger specification– https://github.com/wordnik/swagger-core/wiki

• Swagger Demo– http://petstore.swagger.wordnik.com/

• Wordnik APIs– http://developer.wordnik.com/docs.html#!/account

Make your API accessible

Use Swagger!