Victor introduces Swagger, an open-source framework for describing, producing, consuming, and visualizing RESTful APIs. Swagger allows API developers to describe the structure of APIs, including operations and models, using JSON or YAML files. It also generates documentation from these files and allows for testing API operations in interactive documents.

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

2. Personal
My
name
is
Victor

3. Personal
Java.IL
community
co-­‐founder
http://www.meetup.com/JavaIL/

4. Personal
Full
Stack
Engineer
@

6. http://vatuma.com/demo/wp-content/uploads/2009/11/sun.jpg

7. http://toonclips.com/design/828

8. hFp://www.appdynamics.com/blog/wp-­‐content/uploads/2012/11/producMonCraziness2.png

9. http://thehandcraPedstory.com/wp-content/uploads/2014/08/we-all-have-a-story-to-tell.jpg

10. Architecture
Monolith
to
Micro
Services
APIs
hFps://twiFer.com/dcorpa

11. Architecture
APIs
are
for
humans
DocumentaMon
hFp://www.infoq.com/resource/presentaMons/API-­‐Humans/en/slides/sl23.jpg

12. DocumentaMon

13. DocumentaMon
• No
standard
• Ad-­‐hoc
aFributes
• Managed
manually
• Not
up
to
date
• …..
hFp://www.imagineyourreality.com/business-­‐coaching/documentaMon.html

14. API
LisMng

15. API
OperaMons

16. API
parameters
and
return
types

17. Swagger
is…
Technology
Methodology
A
framework
for
• producing
• consuming
• visualizing
RESTful
APIs
A
specificaMon
for
• describing
• documenMng
RESTful
APIs

18. The
Swagger
SpecificaMon
It’s
a
spec!
• JSON
to
specify
metadata
• JSON
to
specify
API
structure
• JSON
schema
for
the
model
specificaMon
• Machine
readable
• Language
agnosMc

19. Agenda
• IntroducMon
• Deep
Dive
• The
technology
• Swagger
is
not
• Swagger
2.0
• AlternaMves
• References

20. Deep
Dive

21. Swagger
-­‐
API
LisMng

22. Swagger
-­‐
API
LisMng
-­‐
JSON

23. Swagger
–
API
LisMng
-­‐
AnnotaMons

24. Swagger
-­‐
API
Details

25. Swagger
–
Test
the
API

26. Swagger
-­‐
API
Details
-­‐
JSON

27. Swagger
–
API
Details
-­‐
AnnotaMons

28. The
Technology

29. Reverb
-­‐
Wordnik
Atmosphere
–
Scalatra
–
JSON4S

30. The
Technology
–
Scala
based
• swagger-­‐core
• swagger-­‐codegen
• swagger-­‐ui
• swagger-­‐js
• swagger-­‐socket

31. Server
side
integraMons
• Django
• Node.js
• JAX-­‐RS
• RESTEasy
• Grails
• Play
2
• Scalatra
• go-­‐rescul
• SpringMVC
• ServiceStack
.net/MONO
• Swagger-­‐PHP
• Symphony
2
• Grape-­‐swagger
for
Ruby
• Octohipster
for
Clojure
• More…

32. Client
code
generaMon
• Java
• Scala
• Groovy
• Clojure
• Python
• Ruby
• ObjecMveC
• C#
• PHP
• Javascript
• Custom
• Uses
{{mustache}} templates

33. Swagger
is
not

34. • Does
not
support
mulMple
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

35. Swagger
2.0

37. Emerging
Standard
• Thousands
of
developers
contributed
to
the
ecosystem
• Tens
of
thousands
of
producMon
deployments
• From
startups
to
US
Government
http://www.marketwatch.com/story/reverb-announces-swagger-20-a-next-generation-interface-
to-connect-apis-and-cloud-services-2014-09-08?mod=mw_share_twitter

38. Swagger
2.0
• YAML
support
(along
with
JSON)
• OAuth
2.0
enabled
• Migrated
to
Java
• Won’t
be
compaMble
with
1.x

39. Swagger.io

40. Swagger
Tools

41. Swagger
UI

42. Swagger
Tools

43. Swagger
Tools

44. AlternaMves

45. • SOAP/WSDL
– h?p://www.w3.org/TR/wsdl
• WADL
– h?p://en.wikipedia.org/wiki/
Web_ApplicaJon_DescripJon_Language
• Mashery
IO-­‐Docs
– h?p://www.mashery.com/product/io-­‐docs
– h?ps://github.com/mashery/iodocs
• hFp://apiary.io/
• MuleSoP
(RAML)
– h?p://api-­‐portal.anypoint.mulesoL.com/raml-­‐tools?ref=apihub
• Homegrown

46. References
• Swagger
home:
– h?ps://developers.helloreverb.com/swagger/
• Swagger
specificaMon
– h?ps://github.com/wordnik/swagger-­‐core/wiki
• Swagger
Demo
– h?p://petstore.swagger.wordnik.com/
• Swagger.io
• Swagger
editor
– h?p://editor.swagger.io/
• Wordnik
APIs
– h?p://developer.wordnik.com/docs.html#!/account

47. Make
your
API
accessible
Use
Swagger!