A talk given at Code Motion Tel-Aviv

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!