compojure.api.sweet — metosin/compojure-api 1.1.13

ANY clj macro

(ANY & args)

api clj

(api & body)

Returns a ring handler wrapped in compojure.api.middleware/api-middlware. Creates the route-table at api creation time and injects that into the request via middlewares. Api and the mounted api-middleware can be configured by optional options map as the first parameter:

(api
  {:formats [:json-kw :edn :transit-msgpack :transit-json]
   :exceptions {:handlers {:compojure.api.exception/default my-logging-handler}}
   :api {:invalid-routes-fn (constantly nil)}
   :swagger {:spec "/swagger.json"
             :ui "/api-docs"
             :data {:info {:version "1.0.0"
                           :title "My API"
                           :description "the description"}}}}
  (context "/api" []
    ...))

direct api options:

• :api All api options are under :api.
  • :invalid-routes-fn A 2-arity function taking handler and a sequence of invalid routes (not satisfying compojure.api.route.Routing) setting value to nil ignores invalid routes completely. defaults to compojure.api.routes/log-invalid-child-routes
  • :disable-api-middleware? boolean to disable the api-middleware from api.
• :swagger Options to configure the Swagger-routes. Defaults to nil. See compojure.api.swagger/swagger-routes for details.

api-middleware options

Opinionated chain of middlewares for web apis. Takes optional options-map.

Exception handlers

An error handler is a function of exception, ex-data and request to response.

When defining these options, it is suggested to use alias for the exceptions namespace, e.g. [compojure.api.exception :as ex].

Default:

{::ex/request-validation  ex/request-validation-handler
 ::ex/request-parsing     ex/request-parsing-handler
 ::ex/response-validation ex/response-validation-handler
 ::ex/default             ex/safe-handler}

Note: Because the handlers are merged into default handlers map, to disable default handler you need to provide nil value as handler.

Note: To catch Schema errors use {:schema.core/error ex/schema-error-handler}.

Options

• :exceptions for compojure.api.middleware/wrap-exceptions (nil to unmount it)

  • :handlers Map of error handlers for different exception types, type refers to :type key in ExceptionInfo data.

• :format for ring-middleware-format middlewares (nil to unmount it)

  • :formats sequence of supported formats, e.g. [:json-kw :edn]
  • :params-opts for ring.middleware.format-params/wrap-restful-params, e.g. {:transit-json {:handlers readers}}
  • :response-opts for ring.middleware.format-params/wrap-restful-response, e.g. {:transit-json {:handlers writers}}

• :ring-swagger options for ring-swagger's swagger-json method. e.g. {:ignore-missing-mappings? true}

• :coercion A function from request->type->coercion-matcher, used in endpoint coercion for :body, :string and :response. Defaults to (constantly compojure.api.middleware/default-coercion-matchers) Setting value to nil disables all coercion

• :components Components which should be accessible to handlers using :components restructuring. (If you are using api, you might want to take look at using wrap-components middleware manually.). Defaults to nil (middleware not mounted).

context clj macro

(context & args)

defapi clj macro

(defapi name & body)

Defines an api.

API middleware options:

Opinionated chain of middlewares for web apis. Takes optional options-map.

Exception handlers

An error handler is a function of exception, ex-data and request to response.

When defining these options, it is suggested to use alias for the exceptions namespace, e.g. [compojure.api.exception :as ex].

Default:

{::ex/request-validation  ex/request-validation-handler
 ::ex/request-parsing     ex/request-parsing-handler
 ::ex/response-validation ex/response-validation-handler
 ::ex/default             ex/safe-handler}

Note: Because the handlers are merged into default handlers map, to disable default handler you need to provide nil value as handler.

Note: To catch Schema errors use {:schema.core/error ex/schema-error-handler}.

Options

• :exceptions for compojure.api.middleware/wrap-exceptions (nil to unmount it)

  • :handlers Map of error handlers for different exception types, type refers to :type key in ExceptionInfo data.

• :format for ring-middleware-format middlewares (nil to unmount it)

  • :formats sequence of supported formats, e.g. [:json-kw :edn]
  • :params-opts for ring.middleware.format-params/wrap-restful-params, e.g. {:transit-json {:handlers readers}}
  • :response-opts for ring.middleware.format-params/wrap-restful-response, e.g. {:transit-json {:handlers writers}}

• :ring-swagger options for ring-swagger's swagger-json method. e.g. {:ignore-missing-mappings? true}

• :coercion A function from request->type->coercion-matcher, used in endpoint coercion for :body, :string and :response. Defaults to (constantly compojure.api.middleware/default-coercion-matchers) Setting value to nil disables all coercion

• :components Components which should be accessible to handlers using :components restructuring. (If you are using api, you might want to take look at using wrap-components middleware manually.). Defaults to nil (middleware not mounted).

defroutes clj macro

(defroutes name & routes)

Define a Ring handler function from a sequence of routes. The name may optionally be followed by a doc-string and metadata map.

DELETE clj macro

(DELETE & args)

describe clj

(describe schema desc & kvs)

Attach description and possibly other meta-data to a schema.

GET clj macro

(GET & args)

HEAD clj macro

(HEAD & args)

let-routes clj macro

(let-routes bindings & body)

Takes a vector of bindings and a body of routes.

Equivalent to: (let [...] (routes ...))

middleware clj macro

(middleware middleware & body)

Wraps routes with given middlewares using thread-first macro.

Note that middlewares will be executed even if routes in body do not match the request uri. Be careful with middlewares that have side-effects.

OPTIONS clj macro

(OPTIONS & args)

PATCH clj macro

(PATCH & args)

path-for clj macro

(path-for route-name & [params])

Extracts the lookup-table from request and finds a route by name.

POST clj macro

(POST & args)

PUT clj macro

(PUT & args)

resource clj

(resource info)

(resource info options)

Creates a nested compojure-api Route from enchanced ring-swagger operations map and options. By default, applies both request- and response-coercion based on those definitions.

Options:

• :coercion A function from request->type->coercion-matcher, used in resource coercion for :body, :string and :response. Setting value to (constantly nil) disables both request- & response coercion. See tests and wiki for details.

Enchancements to ring-swagger operations map:

1. :parameters use ring request keys (query-params, path-params, ...) instead of swagger-params (query, path, ...). This keeps things simple as ring keys are used in the handler when destructuring the request.

2. at resource root, one can add any ring-swagger operation definitions, which will be available for all operations, using the following rules:

2.1) :parameters are deep-merged into operation :parameters 2.2) :responses are merged into operation :responses (operation can fully override them) 2.3) all others (:produces, :consumes, :summary,...) are deep-merged by compojure-api

3. special key :handler either under operations or at top-level. Value should be a ring-handler function, responsible for the actual request processing. Handler lookup order is the following: operations-level, top-level.

4. request-coercion is applied once, using deep-merged parameters for a given operation or resource-level if only resource-level handler is defined.

5. response-coercion is applied once, using merged responses for a given operation or resource-level if only resource-level handler is defined.

Note: Swagger operations are generated only from declared operations (:get, :post, ..), despite the top-level handler could process more operations.

Example:

(resource {:parameters {:query-params {:x Long}} :responses {500 {:schema {:reason s/Str}}} :get {:parameters {:query-params {:y Long}} :responses {200 {:schema {:total Long}}} :handler (fn [request] (ok {:total (+ (-> request :query-params :x) (-> request :query-params :y))}))} :post {} :handler (constantly (internal-server-error {:reason "not implemented"}))})

routes clj

(routes & handlers)

Create a Ring handler by combining several handlers into one.

swagger-routes clj

(swagger-routes)

(swagger-routes options)

Returns routes for swagger-articats (ui & spec). Accepts an options map, with the following options: :ui Path for the swagger-ui (defaults to "/"). Setting the value to nil will cause the swagger-ui not to be mounted :spec Path for the swagger-spec (defaults to "/swagger.json") Setting the value to nil will cause the swagger-ui not to be mounted :data Swagger data in the Ring-Swagger format. :options :ui Options to configure the ui :spec Options to configure the spec. Nada at the moment. Example options: {:ui "/api-docs" :spec "/swagger.json" :options {:ui {:jsonEditor true} :spec {}} :data {:basePath "/app" :info {:version "1.0.0" :title "Sausages" :description "Sausage description" :termsOfService "http://helloreverb.com/terms/" :contact {:name "My API Team" :email "[e-mail]" :url "http://www.metosin.fi"} :license {:name: "Eclipse Public License" :url: "http://www.eclipse.org/legal/epl-v10.html"}} :tags [{:name "sausages", :description "Sausage api-set"}]}}

undocumented clj

(undocumented & handlers)

Routes without route-documentation. Can be used to wrap routes, not satisfying compojure.api.routes/Routing -protocol.