Migration Guide to 2.0.0

NOTE: Compojure-api 2.0.0 has not been released yet. For a preview, you can try the Compojure-api 2.0.0 alphas. What was supposed to become Compojure-api 1.2.0 will be released as 2.0.0.

About

Compojure-api 2.0.0 has the following breaking changes:

• Compojure-api 2.0.0 requires Java 1.8 or later (because of Muuntaja).
• We now use Muuntaja instead of ring-middleware-format; :format options need migrating
• YAML and msgpack support is not enabled by default
• Request and response coercion now depends on the content type.
• swagger-ui and swagger-docs now take options map instead of varargs.
• middleware has been disabled; use route-middleware instead

The details are below.

NOTE: If you're using version 1.x, please first upgrade to 1.1.13 (the last pre-2.0.0 version) before upgrading to 2.0.0. See also Migration Guide to 1.1.11. If you're using pre-1.0.0 version, see the migration guide to 1.0.0.

• See also the full CHANGELOG.

Muuntaja

We now use Muuntaja instead of ring-middleware-format for format negotiation, encoding, and decoding. In benchmarks, Muuntaja is much faster than ring-middleware-format.

• The api option :format has been removed. Use :formats instead. It should be either a Muuntaja instance, Muuntaja options map, or nil to disable Muuntaja.
• See the instructions for configuring Muuntaja.
  • If you haven't configured :format, you can ignore this.
• By default, support for application/yaml & application/msgpack have been dropped (smaller core). If you want to use them, do this:
  • add a dependency to [metosin/muuntaja-yaml "0.6.0-alpha1"] &/ [metosin/muuntaja-msgpack "0.6.0-alpha1"]
  • configure your api to serve those formats (coercion is pre-set for both):

(require '[muuntaja.core :as m])
(require '[muuntaja.format.yaml])
(require '[muuntaja.format.msgpack])

(api
  {:formats (-> m/default-options)
                (m/install muuntaja.format.yaml/format)
                (m/install muuntaja.format.msgpack/format))}
  ...)

Request and response coercion

Request and response coercion now depends on the format negotiated by Muuntaja. The old default was to coerce all requests and responses with json-coercion-matcher. The new defaults are as follows:

Format	Request	Response
application/edn	validate	validate
application/transit+json	validate	validate
application/transit+msgpack	validate	validate
application/json	json-coercion-matcher	validate
application/msgpack	json-coercion-matcher	validate
application/x-yaml	json-coercion-matcher	validate

How does this affect my routes?

Before, this was ok:

(api
  (GET "/tags" []
    :return {:tags #{s/Keyword}}
    (ok {:tags #{"kikka", "kakka", kukka"}})))

With 2.0.0, it will fail as the return value is not coerced, just validated by default. One can set back the JSON coercion either as default for all formats or for certain formats only:

(require '[compojure.api.coercion.schema :as cs])

;; for all formats
(def json-coerce-all-responses
  (cs/create-coercion
    (assoc-in cs/default-options [:response :default] cs/json-coercion-matcher)))

;; just for application/json
(def json-coerce-responses
  (cs/create-coercion
    (assoc-in cs/default-options [:response :formats "application/json"] cs/json-coercion-matcher)))

(api
  {:coercion json-coerce-all-responses}
  (GET "/tags" []
    :return {:tags #{s/Keyword}}
    (ok {:tags #{"kikka", "kakka", kukka"}})))

• If you have custom coercions, they should continue to work as before.
• default-coercion-matchers has been replaced by default-coercion-options.

middleware and route-middleware

middleware has been disabled because it dangerously applied the middleware even to requests that didn't match the contained routes. Replace it with compojure.api.core/route-middleware, which only applies middleware when the request is matched against the contained routes.

If middleware is needed for backwards-compatibility reasons, set JVM property -Dcompojure.api.core.allow-dangerous-middleware=true.

Still having problems?

If you need help, find us on #ring-swagger in Clojurians Slack (join) or open an issue. If this guide is missing something relevant, feel free to update it. All feedback welcome.