Inline Help

Compojure-api ships with an extendable inline help in compojure.api.help.

Some help

(require '[compojure.api.help :refer [help]])

(help)
; ------------------------------------------------------------
; Usage:
;
; (help)
; (help topic)
; (help topic subject)
;
; Topics:
;
; :meta
;
; Topics & subjects:
;
; :meta :body
; :meta :body-params
; :meta :coercion
; :meta :components
; :meta :consumes
; :meta :description
; :meta :form-params
; :meta :header-params
; :meta :middleware
; :meta :multipart-params
; :meta :name
; :meta :no-doc
; :meta :operationId
; :meta :path-params
; :meta :produces
; :meta :responses
; :meta :return
; :meta :summary
; :meta :swagger
; :meta :tags

More help

(help/help :meta :middleware)
; ------------------------------------------------------------
;
; :middleware
;
; Applies the given vector of middleware to the route.
; Middleware is presented as data in a Duct-style form:
;
; 1) ring mw-function (handler->request->response)
;
; 2) mw-function and it's arguments separately - mw is
;    created by applying function with handler and args
;
; (defn require-role [handler role]
;   (fn [request]
;     (if (has-role? request role)
;       (handler request)
;       (unauthorized))))
;
; (def require-admin (partial require-role :admin))
;
; (GET "/admin" []
;   :middleware [require-admin]
;   (ok))
;
; (GET "/admin" []
;   :middleware [[require-role :admin]]
;   (ok))
;
; (GET "/admin" []
;   :middleware [#(require-admin % :admin)]
;   (ok))
;

Extending help

(defmethod help/help-for [:restructuring :query-params] [_ _]
  (help/text
    "Restructures query-params with plumbing letk notation.\n"
    "Example: read x and optionally y (defaulting to 1)"
    "from query parameters. Body of the endpoint sees the"
    "coerced values.\n"
    (help/code
      "(GET \"/ping\""
      "  :query-params [x :- Long, {y :- Long 1}]"
      "  (ok (+ x y)))")))