Upload
metosin
View
1.797
Download
2
Embed Size (px)
DESCRIPTION
Slides from Clojure Finland March Meetup: Building Swagger-enabled web apis in Clojure (with Compojure-Api & fnhouse)
Citation preview
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