Compojure-api

Stuff on top of Compojure for making sweet web apis.

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

API Docs & Wiki

Latest version

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

See CHANGELOG for details.

For information and help

Read the Version 1.0 Blog Post

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])

(defapi app
  (GET "/hello" []
    :query-params [name :- String]
    (ok {:message (str "Hello, " name)})))

Hello World, async

(require '[clojure.core.async :as a])

(GET "/hello-async" []
  :query-params [name :- String]
  (a/go
    (a/<! (a/timeout 500))
    (ok {:message (str "Hello, " name)})))

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

Hello World, data-driven

(resource
  {:get
   {:parameters {:query-params {:name String}
    :handler (fn [{{:keys [name]} :query-params}]
               (a/go
                 (a/<! (a/timeout 500))
                 (ok {:message (str "Hello, " name)})}}})

Api with Schema & Swagger-docs

(require '[schema.core :as s])

(s/defschema Pizza
 {:name s/Str
  (s/optional-key :description) s/Str
  :size (s/enum :L :M :S)
  :origin {:country (s/enum :FI :PO)
           :city s/Str}})

(def app
 (api
   {:swagger
    {:ui "/api-docs"
     :spec "/swagger.json"
     :data {:info {:title "Sample API"
                   :description "Compojure Api example"}
            :tags [{:name "api", :description "some apis"}]}}}

   (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

https://github.com/metosin/compojure-api/tree/master/examples

Nice full app: https://github.com/yogthos/memory-hole

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

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

Quick start for new project

Clone the examples-repository.

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-2017 Metosin Oy

Distributed under the Eclipse Public License, the same as Clojure.