- The document discusses using Prismatic Schema and Swagger to describe, validate, and document Clojure web APIs. It covers topics like Schema validation and coercion, Ring-Swagger, Compojure-API, and Fnhouse-Swagger integration. - Ring-Swagger implements the Swagger specification for Ring and uses Schema for data models and coercion. Compojure-API is an extendable web API library that uses Schema and generates Swagger documentation. Fnhouse-Swagger provides Swagger support for the Fnhouse library. - The document encourages adopting Schema and Swagger tools to build robust and well-documented Clojure web APIs in a consistent manner across different frameworks.

1. Schema & Swagger
making your Clojure web APIs more awesome
EuroClojure 2014
Tommi Reiman
@ikitommi

2. Topics
• (Too) simple web api in Clojure
• Prismatic Schema
• Swagger
• Ring-swagger
• Compojure-api
• Fnhouse-swagger
• Wrapup

3. (Too) simple web api in Clojure
D
git
clone
h,ps://github.com/ikitommi/euroclojure2014.git

4. The sausage
• Id
• Name
• (Length)
• (Description)
• Origin
– Country
– (City)
h,p://www.sweetpoland.com/

5. How do I program with
sausages?

6. Java Sausage

7. Scala Sausage

8. Clojure Sausage?
Help
me!!

9. Clojure Sausage?
A
Schema
is
a
Clojure(Script)
data
structure
describing
a
data
shape,
which
can
be
used
to
document
and
validate
func=ons
and
data.
h,ps://github.com/prismaAc/schema

10. Schema Sausage?

11. Schema Sausage?

12. Sc validation

13. Bydgoszcz Tampere
h,p://en.wikipedia.org/wiki/Bydgoszcz
h,p://kuvat2.huuto.net/f/4f/1cdb0858b03c69122e9c06f9554a2-­‐orig.jpg

14. Sc elements

15. Sc functions

16. perf

17. perf
“For
now
our
pragmaAc
soluAon
is
to
only
turn
on
validaAon
at
key
boundaries
in
producAon
code
(using
:always-­‐validate),
and
only
check
the
remaining
asserAons
in
tests.
In
pracAce
this
seems
to
catch
nearly
all
the
issues,
without
causing
any
performance
problems.”
-­‐
Jason
Wolfe

18. Sc coercion
Coerce!
Coerce!

19. Sc goodies
• Double schema
• Schema selectors
• Generative Schema
• Schema-tools
• Contribs
• Ring-Swagger

20. Sc goodies
Double
schema

21. Sc goodies
Schema
selectors

22. Sc goodies
h,ps://gist.github.com/davegolland/3bc4277fe109e7b11770
GeneraAve
Schema

23. Sc goodies
h,ps://github.com/PrismaAc/om-­‐tools
Om-­‐tools

24. Sc goodies
h,ps://github.com/sfx/schema-­‐contrib
Contribs
h,ps://github.com/cddr/integrity

25. Sc goodies
h,ps://github.com/metosin/ring-­‐swagger
Ring-­‐Swagger

26. Swagger

27. Swagger
• a specification and complete framework implementation for
describing, producing, consuming, and visualizing RESTful web
services
– https://helloreverb.com/developers/swagger
• Existing adapters for most common web stacks
• Clojure Libs
– Octohipster (https://github.com/myfreeweb/octohipster)
– Swag (https://github.com/narkisr/swag)
– Ring-Swagger
• Compojure-Api (https://github.com/metosin/compojure-api)
• Fnhouse-swagger (https://github.com/metosin/fnhouse-swagger)

28. Resource listing

29. Api declarations

30. (JSON) Schema definitions

31. Swagger UI

32. Swagger UI

33. Code-gen
• Client generators
– Scala, Flash, Java, Objc, PHP, Python, Python3, Ruby
• Javascript via swagger-js
• Also server-stub generators
… no clojure-support yet (anyone?)

34. Swagger-socket
h,ps://github.com/wordnik/swaggersocket

35. Swagger editor

36. Swagger 2.0
coming
up.

37. Ring-Swagger

38. Ring-Swagger
• Swagger implementation for Ring
– https://github.com/metosin/ring-swagger
– Based on Schema for data models coercion
• Extendable mappings of Schemas to JSON Schemas
• Symmetric parsers for common types (inc. Dates, DateTimes)
• Add-ons (coercers, predicates, tools)
– Provides Swagger spec endpoints as Ring routes
• Resource-listing,Api-declarations, Swagger-UI
– Independent to routing-libs
• Currently bindings exist to Compojure-Api and fnHouse

39. Ring-Swagger

40. Ring-Swagger

41. Ring-Swagger

42. Ring-Swagger

43. Ring-Swagger
...
should
be
easier
to
extend.

44. Ring-Swagger-UI
• Jar-packaged version of the Swagger-ui
– https://github.com/metosin/ring-swagger-ui

45. So, where is my
Sausage API?

46. Compojure-api

47. Compojure-Api
• An extendable web api lib on top of Compojure
– https://github.com/metosin/compojure-api
– Macros middlewares with good defaults
– Schema-based models coercion
– Swagger docs

48. Restructured handlers

49. Restructured handlers

50. Restructured handlers

51. Restructured handlers
DIY
:for-­‐roles
[:admin
:user]

52. Sausage API, take one

53. Sausage API, take one
?
D

54. • Macro-fu to reverse-engineer the route tree at
macro-expansion time
– No runtime penalty
– Static routes (no ad-hoc hypermedia)
• Storing compiled route tree in
1) Evil Mutable State, part1: globally side-effecting macro
2) Evil Mutable State, part2: macro-filled global atom
3) Current: Namespace cluttering localVar
4) Next up: DynamicVar?
Route Resolution

55. Route Resolution: Macro-peeling

56. Route Resolution: Macro-peeling

57. Route Resolution: Macro-peeling

58. Swagger it.
D

59. Try it.

60. fnhouse

61. fnhouse
• Fnhouse is a library that
builds on top of ring to
provide a concise way to
write web handlers safely,
readably, without global
variables, without repeating
yourself, and with hooks to
do much more.
• https://github.com/Prismatic/
fnhouse

62. fnhouse
• Defnks with metadata è annotated handler
– Builds on schema plumbing
• Bootstrap: collect defnks wrap to ring-
handlers
• No global state

63. fnhouse
h,ps://www.youtube.com/watch?v=VEDLSvSSMSkindex=27list=PLZdCLR02grLp__wRg5OTavVj4wefg69hM

64. fnhouse-swagger
• https://github.com/metosin/fnhouse-swagger
• fnhouse.swagger (54 loc)
• bootstrap it:

65. Final chapter

66. Schema Swagger
• Prismatic Schema is an awesome tool
– Describe, validate coerce your data
• Swagger to publish out api descriptions
• Building on top of ring-swagger:
– Compojure-api è declarative web apis
– Fnhouse-swagger è meta-data done right
– YourFavouriteWebLib è just do it ( poke us).

67. Next things @ Metosin
• Ring-Swagger
– Make feature complete (+Swagger 2.0)
• Compojure-Api
– Cleanup route-peeling
– Ring-middleware-format
– Repl-tools?
• Help others to adapt
• kekkonen.io
– CQRS-lib

68. Thanks.
@metosin
@ikitommi