Swaggered web apis in Clojure

Swaggered web apis in Clojure

Tommi Reiman @ikitommi

Buzz •  Web apis •  SOA •  REST •  CQRS •  Microservices

Purpose  of  REST  is  to  be  able  to  say  You're  Doing  It  

Wrong  

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)

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

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

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

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

•  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

Schema coersion

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

Compojure-Api

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  

Macro-peeling & source linking

Macro-peeling & source linking

Macro-peeling & source linking

Start programming already.

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

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

fnhouse •  Defnks with web-metadata –  Builds on schema & plumbing

•  Separate steps to collect, wrap to ring-handlers, extract docs

•  Demo

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

The trip •  My first real open sourced libs –  Positive pressure not to deliver crap – Using Travis now for own private projects too

•  Learned a lot, again. •  Met nice new people •  My Lispmacrophilia worn out – …for now at least

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