Compojure-api

Psst! If you're starting a new project, why not try out reitit?

Stuff on top of Compojure for making sweet web apis.

• Schema & clojure.spec (2.0.0) for input & output data coercion
• Swagger for api documentation, via ring-swagger & spec-tools
• Async with async-ring, manifold and core.async (2.0.0)
• Client negotiable formats: JSON, EDN & Transit, optionally YAML and MessagePack
• Data-driven resources
• Bi-directional routing
• Bundled middleware for common api behavior (exception handling, parameters & formats)
• Extendable route DSL via metadata handlers
• Route functions & macros for putting things together, including the Swagger-UI via ring-swagger-ui
• Requires Clojure 1.9.0 & Java 1.8

API Docs & Wiki

Latest version

Latest non-alpha: [metosin/compojure-api "1.1.14"].

See CHANGELOG for details.

For information and help

Read the Version 1.0 Blog Post

Schema & Spec Coercion with 2.0.0

Check wiki for documentation

Clojurians slack (join) has a channel #ring-swagger for talk about any libraries using Ring-swagger. You can also ask questions about Compojure-api and Ring-swagger on other channels at Clojurians Slack or at #clojure on Freenode IRC (mention compojure-api or ring-swagger to highlight us).

Examples

Hello World Api

(require '[compojure.api.sweet :refer:all])
(require '[ring.util.http-response :refer:all])
(defapp
(api
(GET"/hello" []
:query-params [name :- String]
(ok {:message (str"Hello, " name)}))))

Hello World, async

(require '[compojure.api.sweet :refer:all])
(require '[clojure.core.async :as a])
(GET"/hello-async" []
:query-params [name :- String]
(a/go
(a/<! (a/timeout500))
(ok {:message (str"Hello, " name)})))

_{* requires server to be run in async mode}

Hello World, async & data-driven

(require '[compojure.api.sweet :refer:all])
(require '[clojure.core.async :as a])
(require '[schema.core :as s])
(context"/hello-async" []
(resource
{:get
{:parameters {:query-params {:name String}}
:responses {200 {:schema {:message String}}
404 {}
500 {:schema s/Any}}
:handler (fn [{{:keys [name]} :query-params}]
(a/go
(a/<! (a/timeout500))
(ok {:message (str"Hello, " name)})))}}))

_{* Note that empty body responses can be specified with {} or {:schema s/Any}}

Hello World, async, data-driven & clojure.spec

(require '[compojure.api.sweet :refer:all])
(require '[clojure.core.async :as a])
(require '[clojure.spec.alpha :as s])
(s/def::namestring?)
(s/def::messagestring?)
(context"/hello-async" []
(resource
{:coercion:spec:get {:parameters {:query-params (s/keys:req-un [::name])}
:responses {200 {:schema (s/keys:req-un [::message])}}
:handler (fn [{{:keys [name]} :query-params}]
(a/go
(a/<! (a/timeout500))
(ok {:message (str"Hello, " name)})))}}))

Api with Schema & Swagger-docs

(require '[compojure.api.sweet :refer:all])
(require '[schema.core :as s])
(s/defschemaPizza
{:name s/Str
(s/optional-key:description) s/Str
:size (s/enum:L:M:S)
:origin {:country (s/enum:FI:PO)
:city s/Str}})
(defapp
(api
{:swagger
{:ui"/api-docs":spec"/swagger.json":data {:info {:title"Sample API":description"Compojure Api example"}
:tags [{:name"api", :description"some apis"}]
:consumes ["application/json"]
:produces ["application/json"]}}}
(context"/api" []
:tags ["api"]
(GET"/plus" []
:return {:result Long}
:query-params [x :- Long, y :- Long]
:summary"adds two numbers together"
(ok {:result (+ x y)}))
(POST"/echo" []
:return Pizza
:body [pizza Pizza]
:summary"echoes a Pizza"
(ok pizza)))))

More samples

• official samples: https://github.com/metosin/compojure-api/tree/master/examples
• great full app: https://github.com/yogthos/memory-hole
• 2.0.0 sample: https://github.com/metosin/c2
• RESTful CRUD APIs Using Compojure-API and Toucan: https://www.demystifyfp.com/clojure/blog/restful-crud-apis-using-compojure-api-and-toucan-part-1/
• clojurice, An opinionated starter app for full-stack web applications in Clojure: https://github.com/jarcane/clojurice
• Web Development with Clojure, Second Edition: https://pragprog.com/book/dswdcloj2/web-development-with-clojure-second-edition

To try it yourself, clone this repository and do either:

1. lein run
2. lein repl & (go)

Quick start for a new project

Use a Leiningen template, with or without tests:

lein new compojure-api my-api
lein new compojure-api my-api +midje
lein new compojure-api my-api +clojure-test

License

Copyright © 2014-2019 Metosin Oy and contributors.

Distributed under the Eclipse Public License, see LICENSE.