Slides from Clojure Finland March Meetup: Building Swagger-enabled web apis in Clojure (with Compojure-Api & fnhouse)

1. Swaggered web apis in Clojure
Tommi Reiman
@ikitommi

2. Buzz
• Web apis
• SOA
• REST
• CQRS
• Microservices
Purpose
of
REST
is
to
be
able
to
say
You're
Doing
It
Wrong

3. Swagger
• Definition
– Swagger is a specification and complete framework
implementation for describing, producing, consuming, and
visualizing RESTful web services
– https://helloreverb.com/developers/swagger
• Clojure Libs
– Swag (https://github.com/narkisr/swag)
– Octohipster (https://github.com/myfreeweb/octohipster)
– Ring-Swagger
• Compojure-Api (https://github.com/metosin/compojure-api)
• fnhouse (demo) (https://github.com/ikitommi/fnhouse)

4. Ring-Swagger
• New Swagger implementation for Ring
– https://github.com/metosin/ring-swagger
– Based on Schema for data models & coercion
• Mapping of Schemas to JSON Schemas
• Symmetric parsers for common types (inc. Dates, DateTimes)
• Add-ons (coercers, schema predicates, etc.)
– Provides Swagger spec endpoints as Ring routes
• Not yet feature complete, PRs welcome.
– Independent to routing libs
• Currently bindings exist to Compojure-Api & fnhouse
• Why didn’t just use (the otherwise cool)
– Swag? è Has it’s own schema models
– Octohipster? è Married with the Liberator, JSON Schemas

5. Ring-Swagger-UI
• Jar-packaged version of the Swagger-ui
– https://github.com/metosin/ring-swagger-ui
– Follows original npm package versions
• Currently manual building process

6. Ring-http-response
• Real http status codes for Ring-apps
– Ported from Spray (thanks dudes)
– https://github.com/metosin/ring-http-response

7. Compojure-Api
• Dead-simple web api lib on top of Compojure
– https://github.com/metosin/compojure-api
– Macros & middlewares with good defaults for web apis
– Schema-based models, coercion and destructuring
– Swagger documentation

8. • A Schema is a Clojure(Script) data structure
describing a data shape, which can be used to
document and validate functions and data.
– https://github.com/prismatic/schema

9. Schema coersion

10. ring.swagger.schema
• On top of schema.core
– Defmodel (validation & support for nested models)
– Extended json-coercing
– Support for Dates, Keywords, Sets
– Extra meta-data placeholders
– Common predicates

11. Compojure-Api

12. Lispmacrophilia
• Lispmacrophilia, also
called code-
generation-walking-
madness, is the
uncontrollable urge
to play with the lisp
macros.
Compile-­‐>me
Run-­‐>me
©
Federal
Prac>ce
Group
A
macro

13. Macro-peeling & source linking

14. Macro-peeling & source linking

15. Macro-peeling & source linking

16. Start programming already.

17. Next things, maybe
• Ring-Swagger
– Support for vanilla schemas
– Make feature complete
• Compojure-Api
– Lein-template
– Bidi, bidi, bidi!
– Typed query & path params
– FILE*,WS*
• kekkonen.io
– The CQRS-lib

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

19. fnhouse
• Defnks with web-metadata
– Builds on schema & plumbing
• Separate steps to collect, wrap to ring-handlers,
extract docs
• Demo

20. fnhouse & ring-swagger?
• https://github.com/ikitommi/fnhouse
• fnhouse.swagger (42 loc)
• bootstrap it:

21. The trip
• My first real open sourced libs
– Positive pressure not to deliver crap
– UsingTravis now for own private projects too
• Learned a lot, again.
• Met nice new people
• My Lispmacrophilia worn out
– …for now at least

22. Takeaways
• Swagger and Schema are awesome
• The libs (pull requests welcome!)
– Ring-http-request - for http-requests
– Ring-Swagger - brings Swagger to Ring apps
– Compojure Api - to build web apis
• Fnhouse kicks ass
– & with Swagger
• Follow @ikitommi, @metosin & @PrismaticEng for
updates