This document introduces Swagger, an open-source framework for describing, producing, consuming, and visualizing RESTful APIs. It provides a specification for describing APIs in a machine-readable format. Swagger allows automatically generating documentation from code and enabling tooling around REST APIs. The document discusses Swagger specifications, how to list and view API details, integration with various programming languages and frameworks, development and deployment processes, and alternatives to Swagger.

1. Swagger
Make your API accessible
Victor Trakhtenberg
victortr75@gmail.com @victortr75

2. Personal
My name is Victor
Almost 15 years of software development
Chief Architect @

3. Architecture
SOA
APIs
https://twitter.com/dcorpa

4. Architecture
APIs are for humans
Documentation
http://www.infoq.com/resource/presentations/API-Humans/en/slides/sl23.jpg

5. Documentation

6. Documentation
• No standard
• Ad-hoc attributes
• Managed manually
• Not up to date
• …..
http://www.imagineyourreality.com/business-coaching/documentation.html

7. API Listing

8. API Operations

9. API parameters and return types

10. Swagger is…
• producing
• consuming
• visualizing
RESTful APIs
A framework
for
• describing
• documenting
RESTful APIs
A specification
for
Technology Methodology

11. 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

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

13. Deep Dive

14. Swagger - API Listing

15. Swagger - API Listing - JSON

16. Swagger – API Listing - Annotations

17. Swagger - API Details

18. Swagger – Test the API

19. Swagger - API Details - JSON

20. Swagger – API Details - Annotations

21. The Technology

22. Reverb - Wordnik
Atmosphere – Scalatra – JSON4S

23. The Technology – Scala based
• swagger-core
• swagger-codegen
• swagger-ui

24. 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…

25. Client code generation
• Java
• Scala
• Groovy
• Clojure
• Python
• Ruby
• ObjectiveC
• C#
• PHP
• Javascript
• Custom
• Uses {{mustache}} templates

26. Swagger is not

27. • 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

28. Alternatives

29. • SOAP/WSDL
– http://www.w3.org/TR/wsdl
• WADL
– http://en.wikipedia.org/wiki/Web_Application_Descriptio
n_Language
• Mashery IO-Docs
– http://www.mashery.com/product/io-docs
– https://github.com/mashery/iodocs
• http://apiary.io/
• Homegrown

30. Dev Process

31. API development approaches
API specification first
–Write the JSON spec
–Generate the API stubs
–Implement the APIs
–Publish

32. API development approaches
API implementation first
–Implement the API
–Put the annotations in place

33. Deployment Process

34. Dev/Test environment
Annotate the APIs
Make swagger UI accessible from
the application itself

35. Dev/Test environment
View the documentation locally
Test the APIs using swagger UI

36. Dev/Test environment
Generate internal clients based on
swagger specification

37. Production environment
Make swagger UI
NOT accessible from the application
itself

38. Production environment
Automatically generate external
swagger static resources

39. Production environment
Deploy on dedicated web server
Synchronize the documentation

40. Production environment
Generate external clients based on
swagger specification

41. 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

42. Make your API accessible
Use Swagger!