Merge pull request #762 from metosin/745-coerce-response-content-type

improve & document response coercion content-type selection

CHANGELOG.md

@@ -12,6 +12,10 @@ We use [Break Versioning][breakver]. The version numbers follow a `<major>.<mino
 
 [breakver]: https://github.com/ptaoussanis/encore/blob/master/BREAK-VERSIONING.md
 
+## UNRELEASED
+
+* Improve & document how response schemas get picked in per-content-type coercion. See [docs](./doc/ring/coercion.md#per-content-type-coercion). [#745](https://github.com/metosin/reitit/issues/745).
+
 ## 0.9.2 (2025-10-28)
 
 * Allow multimethods as handlers when validating [#755](https://github.com/metosin/reitit/pull/755)

doc/ring/coercion.md

@@ -202,9 +202,11 @@ is:
                                                     "application/edn" {:schema {:x s/Int}}
                                                     :default {:schema {:ww s/Int}}}}}
                          :handler ...}}]]
-    {:data {:middleware [rrc/coerce-exceptions-middleware
+    {:data {:muuntaja muuntaja.core/instance
-                         rrc/coerce-request-middleware
+            :middleware [reitit.ring.middleware.muuntaja/format-middleware
-                         rrc/coerce-response-middleware]}})))
+                         reitit.ring.coercion/coerce-exceptions-middleware
+                         reitit.ring.coercion/coerce-request-middleware
+                         reitit.ring.coercion/coerce-response-middleware]}})))
 ```
 
 The resolution logic for response coercers is:
@@ -215,6 +217,17 @@ The resolution logic for response coercers is:
    3. `:body`
 3. If nothing was found, do not coerce
 
+To select the response content-type, you can either:
+1. Let muuntaja pick the content-type based on things like the request Accept header
+   - This is what most users want
+2. Set `:muuntaja/content-type` in the response to pick an explicit content type
+3. Set the `"Content-Type"` header in the response
+   - This disables muuntaja, so you need to encode your response body in some other way!
+   - This is not compatible with response schema checking, since coercion won't know what to do with the already-encoded response body.
+4. Use the `:extract-response-format` option to inject your own logic. See `reitit.coercion/extract-response-format-default` for the default.
+
+See also the [muuntaja content negotiation](./content_negotiation.md) docs.
+
 ## Pretty printing spec errors
 
 Spec problems are exposed as is in request & response coercion errors. Pretty-printers like [expound](https://github.com/bhb/expound) can be enabled like this:

examples/openapi/src/example/server.clj

@@ -52,23 +52,34 @@
         {:get {:summary "Fetch a pizza | Multiple content-types, multiple examples"
                :responses {200 {:description "Fetch a pizza as json or EDN"
                                 :content {"application/json" {:schema [:map
+                                                                       [:format [:enum :json]]
                                                                        [:color :keyword]
                                                                        [:pineapple :boolean]]
                                                               :examples {:white {:description "White pizza with pineapple"
-                                                                                 :value {:color :white
+                                                                                 :value {:format :json
+                                                                                         :color :white
                                                                                          :pineapple true}}
                                                                          :red {:description "Red pizza"
-                                                                               :value {:color :red
+                                                                               :value {:format :json
+                                                                                       :color :red
                                                                                        :pineapple false}}}}
                                           "application/edn" {:schema [:map
+                                                                      [:format [:enum :edn]]
                                                                       [:color :keyword]
                                                                       [:pineapple :boolean]]
                                                              :examples {:red {:description "Red pizza with pineapple"
-                                                                              :value (pr-str {:color :red :pineapple true})}}}}}}
+                                                                              :value (pr-str {:format :edn :color :red :pineapple true})}}}}}}
                :handler (fn [_request]
+                          (rand-nth [{:status 200
+                                      :muuntaja/content-type "application/json"
+                                      :body {:format :json
+                                             :color :red
+                                             :pineapple true}}
                                      {:status 200
-                           :body {:color :red
+                                      :muuntaja/content-type "application/edn"
-                                  :pineapple true}})}
+                                      :body {:format :edn
+                                             :color :red
+                                             :pineapple true}}]))}
          :post {:summary "Create a pizza | Multiple content-types, multiple examples | Default response schema"
                 :request {:description "Create a pizza using json or EDN"
                           :content {"application/json" {:schema [:map

modules/reitit-core/src/reitit/coercion.cljc

@@ -152,8 +152,10 @@
          rcs (request-coercers coercion parameters (cond-> opts route-request (assoc ::skip #{:body})))]
      (if (and crc rcs) (into crc (vec rcs)) (or crc rcs)))))
 
-(defn extract-response-format-default [request _]
+(defn extract-response-format-default [request response]
-  (-> request :muuntaja/response :format))
+  (or (get-in response [:headers "Content-Type"])
+      (:muuntaja/content-type response)
+      (-> request :muuntaja/response :format)))
 
 (defn -format->coercer [coercion {:keys [content body]} _opts]
   (->> (concat (when body

test/cljc/reitit/ring_coercion_test.cljc

@@ -1,8 +1,10 @@
 (ns reitit.ring-coercion-test
   (:require [clojure.test :refer [deftest is testing]]
             [malli.experimental.lite :as l]
-            #?@(:clj [[muuntaja.middleware]
+            #?@(:clj [[muuntaja.core]
-                      [jsonista.core :as j]])
+                      [muuntaja.middleware]
+                      [jsonista.core :as j]
+                      [reitit.ring.middleware.muuntaja]])
             [malli.core :as m]
             [malli.util :as mu]
             [meta-merge.core :refer [meta-merge]]
@@ -585,6 +587,8 @@
 
 #?(:clj
 (deftest per-content-type-test
+  (let [normalize-json (fn [resp]
+                         (update resp :body #(-> % j/write-value-as-string (j/read-value j/keyword-keys-object-mapper))))]
     (doseq [[coercion json-request edn-request default-request json-response edn-response default-response]
             [[malli/coercion
               [:map [:request [:enum :json]] [:response any?]]
@@ -654,9 +658,7 @@
                              :uri "/foo"
                              :muuntaja/request {:format request-format}
                              :muuntaja/response {:format response-format}
-                           :body-params body})
+                             :body-params body})]
-                normalize-json (fn[body]
-                                 (-> body j/write-value-as-string (j/read-value j/keyword-keys-object-mapper)))]
               (testing "succesful call"
                 (is (= {:status 200 :body {:request "json", :response "json"}}
                        (normalize-json (call (request "application/json" "application/json" {:request :json :response :json})))))
@@ -677,7 +679,39 @@
                 (is (= {:type :reitit.coercion/response-coercion :in [:response :body]}
                        (call (request "application/json" "application/edn" {:request :json :response :json}))))
                 (is (= {:type :reitit.coercion/response-coercion :in [:response :body]}
-                     (call (request "application/json" "application/transit" {:request :json :response :json}))))))))))))
+                       (call (request "application/json" "application/transit" {:request :json :response :json}))))))))
+        (testing "explicit response content type"
+          (let [response (atom nil)
+                app (ring/ring-handler
+                     (ring/router
+                      ["/foo" {:post {:responses {200 {:content {"application/json" {:schema json-response}
+                                                                 "application/edn" {:schema edn-response}
+                                                                 :default {:schema default-response}}}}
+                                      :handler (fn [req]
+                                                 @response)}}]
+                      {:validate reitit.ring.spec/validate
+                       :data {:middleware [rrc/coerce-request-middleware
+                                           rrc/coerce-response-middleware]
+                              :coercion coercion}}))
+                call (fn [request]
+                       (try
+                         (app request)
+                         (catch ExceptionInfo e
+                           #_(ex-data e)
+                           (select-keys (ex-data e) [:type :in]))))
+                request (fn [request-format body resp]
+                          (reset! response resp)
+                          {:request-method :post
+                           :uri "/foo"
+                           :muuntaja/request {:format request-format}
+                           :body-params body})]
+            (testing "via :muuntaja/content-type"
+              (is (= {:status 200 :body {:request "json" :response "json"} :muuntaja/content-type "application/json"}
+                     (normalize-json (call (request "application/json" {:request :json :response :json} {:status 200 :body {:request :json :response :json} :muuntaja/content-type "application/json"}))))
+                  "valid reponse")
+              (is (= {:in [:response :body] :type :reitit.coercion/response-coercion}
+                     (call (request "application/json" {:request :json :response :json} {:status 200 :body {:request :json :response :invalid} :muuntaja/content-type "application/json"})))
+                  "invalid reponse")))))))))
 
 
 #?(:clj
@@ -801,3 +835,100 @@
                         (app) :body slurp (read-string))]
            (is (= data-edn (e2e (assoc data-edn :EXTRA "VALUE"))))
            (is (thrown? ExceptionInfo (e2e data-json))))))))
+
+#?(:clj
+   (deftest muuntaja-per-content-type-coercion-test
+     ;; Test integration between per-content-type coercion and muuntaja.
+     ;; Malli-only for now.
+     (let [response (atom nil)
+           app (ring/ring-handler
+                (ring/router
+                 ["/foo" {:post {:request {:content {"application/json" {:schema [:map [:request [:enum :json]]]}
+                                                     "application/edn" {:schema [:map [:request [:enum :edn]]]}
+                                                     :default {:schema [:map [:request [:enum :default]]]}}}
+                                 :responses {200 {:content {"application/json" {:schema [:map [:response [:enum :json]]]}
+                                                            "application/edn" {:schema [:map [:response [:enum :edn]]]}
+                                                            :default {}}}}
+                                 :handler (fn [req] @response)}}]
+                 {:data {:middleware [reitit.ring.middleware.muuntaja/format-middleware
+                                      rrc/coerce-request-middleware
+                                      rrc/coerce-response-middleware]
+                         :muuntaja muuntaja.core/instance
+                         :coercion malli/coercion}}))
+           maybe-slurp #(if (instance? java.io.InputStream %)
+                          (slurp %)
+                          %)
+           call (fn [request resp]
+                  (reset! response resp)
+                  (try
+                    (-> (merge {:request-method :post :uri "/foo"} request)
+                        (update :body #(ByteArrayInputStream. (.getBytes % "UTF-8")))
+                        (app))
+                    (catch ExceptionInfo e
+                      #_(ex-data e)
+                      (select-keys (ex-data e) [:in :type]))))
+           read-json #(j/read-value % (j/object-mapper {:decode-key-fn true}))
+           json-response? (fn [resp]
+                            (and (.startsWith (get-in resp [:headers "Content-Type"]) "application/json") ;; ignore the ;charset=utf-8 part
+                                 (= {:response "json"} (read-json (maybe-slurp (:body resp))))))
+           edn-response? (fn [resp]
+                           (and (.startsWith (get-in resp [:headers "Content-Type"]) "application/edn") ;; ignore the ;charset=utf-8 part
+                                (= {:response :edn} (read-string (maybe-slurp (:body resp))))))
+           custom-response? (fn [resp]
+                              (and (= (get-in resp [:headers "Content-Type"]) "application/custom")
+                                   (= "custom data" (maybe-slurp (:body resp)))))]
+       (testing "response content-type defaults to json"
+         (is (json-response?
+              (call {:headers {"content-type" "application/json"}
+                     :body (j/write-value-as-string {:request :json})}
+                    {:status 200
+                     :body {:response :json}})))
+         (is (json-response?
+              (call {:headers {"content-type" "application/edn"}
+                     :body (pr-str {:request :edn})}
+                    {:status 200
+                     :body {:response :json}})))
+         (is (= {:in [:response :body] :type :reitit.coercion/response-coercion}
+                (call {:headers {"content-type" "application/json"}
+                       :body (j/write-value-as-string {:request :json})}
+                      {:status 200
+                       :body {:response :invalid}}))
+             "invalid response"))
+       (testing "response content-type negotiated via accept header"
+         (is (json-response?
+              (call {:headers {"content-type" "application/json" "accept" "application/json"}
+                     :body (j/write-value-as-string {:request :json})}
+                    {:status 200
+                     :body {:response :json}})))
+         (is (edn-response?
+              (call {:headers {"content-type" "application/json" "accept" "application/edn"}
+                     :body (j/write-value-as-string {:request :json})}
+                    {:status 200
+                     :body {:response :edn}})))
+         (is (= {:in [:response :body] :type :reitit.coercion/response-coercion}
+                (call {:headers {"content-type" "application/json" "accept" "application/edn"}
+                       :body (j/write-value-as-string {:request :json})}
+                      {:status 200
+                       :body {:response :invalid}}))
+             "invalid response"))
+       (testing "response content-type set via :muuntaja/content-type"
+         (is (edn-response?
+              (call {:headers {"content-type" "application/json" "accept" "application/json"}
+                     :body (j/write-value-as-string {:request :json})}
+                    {:status 200
+                     :muuntaja/content-type "application/edn"
+                     :body {:response :edn}})))
+         (is (= {:in [:response :body] :type :reitit.coercion/response-coercion}
+                (call {:headers {"content-type" "application/json" "accept" "application/json"}
+                       :body (j/write-value-as-string {:request :json})}
+                      {:status 200
+                       :muuntaja/content-type "application/edn"
+                       :body {:response :invalid}}))
+             "invalid response"))
+       (testing "response content-type set via Content-Type header. muuntaja disabled for response."
+         (is (custom-response?
+              (call {:headers {"content-type" "application/json" "accept" "application/json"}
+                     :body (j/write-value-as-string {:request :json})}
+                    {:status 200
+                     :headers {"Content-Type" "application/custom"}
+                     :body "custom data"})))))))