From 699a8c7cd37cbe1b05e84e97a03bc72810f4d738 Mon Sep 17 00:00:00 2001
From: Tommi Reiman <tommi@iki.fi>
Date: Sun, 29 Dec 2019 11:17:20 +0200
Subject: [PATCH] docs

---
 README.md                      |  1 -
 doc/coercion/coercion.md       |  1 +
 doc/coercion/malli_coercion.md | 45 ++++++++++++++++++++++++++++++++++
 doc/ring/coercion.md           |  1 +
 4 files changed, 47 insertions(+), 1 deletion(-)
 create mode 100644 doc/coercion/malli_coercion.md

diff --git a/README.md b/README.md
index 16d73548..62acf913 100644
--- a/README.md
+++ b/README.md
@@ -1,6 +1,5 @@
 # reitit [![Build Status](https://img.shields.io/circleci/project/github/metosin/reitit.svg)](https://circleci.com/gh/metosin/reitit) [![cljdoc badge](https://cljdoc.xyz/badge/metosin/reitit)](https://cljdoc.xyz/jump/release/metosin/reitit) [![Slack](https://img.shields.io/badge/clojurians-reitit-blue.svg?logo=slack)](https://clojurians.slack.com/messages/reitit/)
 
-
 A fast data-driven router for Clojure(Script).
 
 * Simple data-driven [route syntax](https://metosin.github.io/reitit/basics/route_syntax.html)
diff --git a/doc/coercion/coercion.md b/doc/coercion/coercion.md
index 04f9ad10..eb7ca035 100644
--- a/doc/coercion/coercion.md
+++ b/doc/coercion/coercion.md
@@ -36,6 +36,7 @@ To enable parameter coercion, the following things need to be done:
 
 Reitit ships with the following coercion modules:
 
+* `reitit.coercion.malli/coercion` for [malli](https://github.com/metosin/malli)
 * `reitit.coercion.schema/coercion` for [plumatic schema](https://github.com/plumatic/schema)
 * `reitit.coercion.spec/coercion` for both [clojure.spec](https://clojure.org/about/spec) and [data-specs](https://github.com/metosin/spec-tools#data-specs)
 
diff --git a/doc/coercion/malli_coercion.md b/doc/coercion/malli_coercion.md
new file mode 100644
index 00000000..b9627215
--- /dev/null
+++ b/doc/coercion/malli_coercion.md
@@ -0,0 +1,45 @@
+# Malli Coercion
+
+[Malli](https://github.com/metosin/malli) is data-driven Schema library for Clojure/Script.
+
+```clj
+(require '[reitit.coercion.malli])
+(require '[reitit.coercion :as coercion])
+(require '[reitit.core :as r])
+
+(def router
+  (r/router
+    ["/:company/users/:user-id" {:name ::user-view
+                                 :coercion reitit.coercion.malli/coercion
+                                 :parameters {:path [:map
+                                                     [:company string?]
+                                                     [:user-id int?]]}]
+    {:compile coercion/compile-request-coercers}))
+
+(defn match-by-path-and-coerce! [path]
+  (if-let [match (r/match-by-path router path)]
+    (assoc match :parameters (coercion/coerce! match))))
+```
+
+Successful coercion:
+
+```clj
+(match-by-path-and-coerce! "/metosin/users/123")
+; #Match{:template "/:company/users/:user-id",
+;        :data {:name :user/user-view,
+;               :coercion <<:malli>>
+;               :parameters {:path [:map
+;                                   [:company string?]
+;                                   [:user-id int?]]}},
+;        :result {:path #object[reitit.coercion$request_coercer$]},
+;        :path-params {:company "metosin", :user-id "123"},
+;        :parameters {:path {:company "metosin", :user-id 123}}
+;        :path "/metosin/users/123"}
+```
+
+Failing coercion:
+
+```clj
+(match-by-path-and-coerce! "/metosin/users/ikitommi")
+; => ExceptionInfo Request coercion failed...
+```
diff --git a/doc/ring/coercion.md b/doc/ring/coercion.md
index 50086ac6..a8ddae6f 100644
--- a/doc/ring/coercion.md
+++ b/doc/ring/coercion.md
@@ -25,6 +25,7 @@ To enable coercion, the following things need to be done:
 
 Reitit ships with the following coercion modules:
 
+* `reitit.coercion.malli/coercion` for [malli](https://github.com/metosin/malli)
 * `reitit.coercion.schema/coercion` for [plumatic schema](https://github.com/plumatic/schema)
 * `reitit.coercion.spec/coercion` for both [clojure.spec](https://clojure.org/about/spec) and [data-specs](https://github.com/metosin/spec-tools#data-specs)