From 48fdb692ef315caa63ceaf9df18dfdce95fbd814 Mon Sep 17 00:00:00 2001
From: Joel Kaasinen <joel.kaasinen@metosin.fi>
Date: Fri, 23 May 2025 12:56:01 +0300
Subject: [PATCH] doc: improve ring example in README.md

- format-response-middleware wasn't doing anything, use
  format-middleware instead as that's what the users usually want
- add exception handling
- document middleware stack a bit
---
 README.md | 51 +++++++++++++++++++++++++++++----------------------
 1 file changed, 29 insertions(+), 22 deletions(-)

diff --git a/README.md b/README.md
index 9906134d..44ffcf6a 100644
--- a/README.md
+++ b/README.md
@@ -1,4 +1,4 @@
-# reitit 
+# reitit
 
 [![Build Status](https://github.com/metosin/reitit/actions/workflows/testsuite.yml/badge.svg)](https://github.com/metosin/reitit/actions)
 [![cljdoc badge](https://cljdoc.org/badge/metosin/reitit)](https://cljdoc.org/d/metosin/reitit/)
@@ -54,7 +54,7 @@ There is [#reitit](https://clojurians.slack.com/messages/reitit/) in [Clojurians
 * `metosin/reitit-sieppari` support for [Sieppari](https://github.com/metosin/sieppari)
 * `metosin/reitit-dev` - development utilities
 
-... * This is not a typo; the new `reitit-openapi` was released under the new, verified `fi.metosin` group. Existing 
+... * This is not a typo; the new `reitit-openapi` was released under the new, verified `fi.metosin` group. Existing
 modules will continue to be released under `metosin` for compatibility purposes.
 
 ## Extra modules
@@ -109,6 +109,7 @@ A Ring routing app with input & output coercion using [data-specs](https://githu
 (require '[reitit.ring :as ring])
 (require '[reitit.coercion.spec])
 (require '[reitit.ring.coercion :as rrc])
+(require '[reitit.ring.middleware.exception :as exception])
 (require '[reitit.ring.middleware.muuntaja :as muuntaja])
 (require '[reitit.ring.middleware.parameters :as parameters])
 
@@ -124,39 +125,45 @@ A Ring routing app with input & output coercion using [data-specs](https://githu
       ;; router data affecting all routes
       {:data {:coercion   reitit.coercion.spec/coercion
               :muuntaja   m/instance
-              :middleware [parameters/parameters-middleware
+              :middleware [parameters/parameters-middleware ; decoding query & form params
+                           muuntaja/format-middleware       ; content negotiation
+                           exception/exception-middleware   ; converting exceptions to HTTP responses
                            rrc/coerce-request-middleware
-                           muuntaja/format-response-middleware
                            rrc/coerce-response-middleware]}})))
 ```
 
 Valid request:
 
 ```clj
-(app {:request-method :get
-      :uri "/api/math"
-      :query-params {:x "1", :y "2"}})
+(-> (app {:request-method :get
+          :uri "/api/math"
+          :query-params {:x "1", :y "2"}})
+    (update :body slurp))
 ; {:status 200
-;  :body {:total 3}}
+;  :body "{\"total\":3}"
+;  :headers {"Content-Type" "application/json; charset=utf-8"}}
 ```
 
 Invalid request:
 
 ```clj
-(app {:request-method :get
-      :uri "/api/math"
-      :query-params {:x "1", :y "a"}})
-;{:status 400,
-; :body {:type :reitit.coercion/request-coercion,
-;        :coercion :spec,
-;        :spec "(spec-tools.core/spec {:spec (clojure.spec.alpha/keys :req-un [:$spec20745/x :$spec20745/y]), :type :map, :keys #{:y :x}, :keys/req #{:y :x}})",
-;        :problems [{:path [:y],
-;                    :pred "clojure.core/int?",
-;                    :val "a",
-;                    :via [:$spec20745/y],
-;                    :in [:y]}],
-;        :value {:x "1", :y "a"},
-;        :in [:request :query-params]}}
+(-> (app {:request-method :get
+          :uri "/api/math"
+          :query-params {:x "1", :y "a"}})
+    (update :body jsonista.core/read-value))
+; {:status 400
+;  :headers {"Content-Type" "application/json; charset=utf-8"}
+;  :body {"spec" "(spec-tools.core/spec {:spec (clojure.spec.alpha/keys :req-un [:spec$8974/x :spec$8974/y]), :type :map, :leaf? false})"
+;         "value" {"x" "1"
+;                  "y" "a"}
+;         "problems" [{"via" ["spec$8974/y"]
+;                      "path" ["y"]
+;                      "pred" "clojure.core/int?"
+;                      "in" ["y"]
+;                      "val" "a"}]
+;         "type" "reitit.coercion/request-coercion"
+;         "coercion" "spec"
+;         "in" ["request" "query-params"]}}
 ```
 
 ## More examples